nezam-token-grid-typography

name	nezam-token-grid-typography
description	Token + grid systems — CSS Grid/Flex, container queries, clamp() typography, breakpoint matrices.
version	1.0.0
updated	"2026-05-08T00:00:00.000Z"
changelog	[]
tier	2
breaking_changes	false

Purpose

Define and enforce a deterministic token, typography, and layout grid foundation for React UI work before component implementation. Single-responsibility: typography + grid + container-query matrix. (Absorbs the previously-proposed nezam-grid-systems.)

Inputs

• docs/DESIGN.md typography, spacing, and layout sections.
• docs/specs/SEO_RESEARCH.md and IA constraints when available.
• Brand direction notes and editorial style intent.
• Existing token drafts or legacy style variables.
• Page templates + component inventories from @.cursor/skills/nezam-component-library-api/SKILL.md.

Step-by-Step Workflow

1. Extract design primitives from docs/DESIGN.md into categories: color, spacing, radius, typography, shadow, z-index, motion.
2. Normalize into W3C-style token JSON (base + semantic tiers); pair with @.cursor/skills/nezam-pro-design-tokens/SKILL.md.
3. Define typography scale with clamp(min, preferred, max) for each role (display, h1..h6, body, caption, label); set line-height + letter-spacing tokens.
4. Create breakpoint and container matrices (mobile, tablet, desktop, wide); map layout tokens to each tier.
5. Emit CSS variable layers (:root, theme scopes, dark-mode scope); avoid inline literal fallbacks except governed defaults.
6. Define macro grid patterns with CSS Grid (page + section level) and micro-layout rules with Flex utilities; both consume spacing tokens.
7. Adopt container queries (@container) for components that vary by parent width rather than viewport.
8. Produce component-level token alias guidance (e.g., --surface-card, --text-muted) to isolate implementation from base-token churn.
9. Add drift detection: lint hardcoded spacing/color/type values outside approved token sources.
10. Hand off contracts to @.cursor/skills/nezam-component-library-api/SKILL.md and motion roles for cross-system parity.

Validation & Metrics

• Token coverage: 100% of spacing/color/type/radius/z-index references map to tokens.
• Typographic fluidity: all text roles use clamp() with min/preferred/max pattern.
• Layout stability: CLS target < 0.1 under responsive transitions.
• Performance: no heavy runtime style generation; static CSS variable resolution.
• Accessibility: type contrast pairings satisfy WCAG 2.2 AA.
• Consistency: no duplicate semantic tokens with conflicting meanings.

Output Format

• tokens/base.json (raw scales).
• tokens/semantic.json (usage semantics).
• css/tokens.css (:root + theme scopes).
• css/grid.css (macro + container rules).
• docs/specs/TYPOGRAPHY_GRID_MATRIX.md (reference table).

Integration Hooks

• /PLAN design: run before approving visual specs.
• /DEVELOP: block component work until token contracts exist.
• /SCAN code|a11y|perf: enforce token + typography checks.
• CI: add token drift and hardcoded-value lint gates.
• Pairs with @.cursor/skills/nezam-pro-design-tokens/SKILL.md, @.cursor/skills/nezam-component-library-api/SKILL.md, @.cursor/skills/nezam-motion-3d-progressive/SKILL.md, @.cursor/skills/nezam-react-architecture/SKILL.md.
• Enforces [.cursor/rules/design-dev-gates.mdc](.cursor/rules/design-dev-gates.mdc) Gates 1 & 2 and [.cursor/rules/nezam-design-gates-pro.mdc](.cursor/rules/nezam-design-gates-pro.mdc).

Anti-Patterns

• Ad-hoc px values inside utility classes.
• Static breakpoints without container-query consideration for reusable components.
• Typography defined as fixed font-size per breakpoint instead of clamp().
• Mixing flex and grid for the same layout intent without a documented decision.
• Component classes that bypass tokens for "one-off" layouts.

External Reference

• W3C CSS Grid Level 2 + Container Queries (https://www.w3.org/TR/css-contain-3/) — current.
• MDN clamp(), @container, grid-template (current).
• W3C Design Tokens Format Module (https://design-tokens.github.io/community-group/format/).
• WCAG 2.2 (https://www.w3.org/TR/WCAG22/).
• Closest skills.sh/official analog: typography-grid / responsive-css.