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