Skip to content

docs(tokens): add Diátaxis documentation for grid, spacing, typography, and cascade layers#550

Open
advl wants to merge 1 commit intomainfrom
ft-style-documentation
Open

docs(tokens): add Diátaxis documentation for grid, spacing, typography, and cascade layers#550
advl wants to merge 1 commit intomainfrom
ft-style-documentation

Conversation

@advl
Copy link
Copy Markdown
Contributor

@advl advl commented Mar 24, 2026

Done

  • Add 10 new MDX documentation files following the Diátaxis framework (explanations, how-to guides, tutorials, reference)
  • Add SpacingScale and TypographyScale story exports to Tokens.stories.tsx
  • Restructure hub Introduction.mdx to surface the Diátaxis navigation map

New documentation files

Explanations

  • GridSystem.mdx — why responsive vs intrinsic, modifier pattern in the grid, why subgrid
  • SpacingScale.mdx — 8px base unit, half-step refinements, rem rationale, baseline grid relationship

How-to guides

  • HowToUseResponsiveGrid.mdx — 5-step breakpoint-driven column layout recipe
  • HowToUseIntrinsicGrid.mdx — 4-step fluid content-driven layout recipe
  • HowToForceTheme.mdx — 5-step dark/light subtree override
  • HowToDebugTokens.mdx — 6-step DevTools token tracing
  • HowToAlignBaseline.mdx — 5-step baseline grid alignment

Tutorial

  • TutorialFirstGrid.mdx — 7-step guided dashboard layout build

Reference

  • GridReference.mdx — all grid classes, custom properties, breakpoints, browser support
  • CascadeLayersReference.mdx — the 5-layer cascade architecture with all modifier channels

New story exports

  • SpacingScale — visual bar chart of all 17 dimension tokens with rem/px values and baseline-grid markers, common spacing patterns, and a TokenTable explorer
  • TypographyScale — live-rendered heading 1–6 previews, text primary/secondary/tertiary with bold variants, and a 5-token structure reference

Hub update

  • Introduction.mdx — added Diátaxis navigation map (🎓 Learn / 🔧 How to / 💡 Understanding / 📖 Reference), corrected modifier ontology to four axes (Importance, Anticipation, Criticality, Emphasis)

QA

  • Run nx storybook ds-tokens and verify all new stories render without errors
  • Verify SpacingScale story shows 17 dimension tokens with visual bars and ◆ baseline markers
  • Verify TypographyScale story shows heading 1–6 and text styles with live previews
  • Navigate to each new MDX doc page and confirm Storybook doc blocks render correctly
  • Run nx storybook storybook-hub and verify the updated Introduction page renders the Diátaxis navigation map
  • Confirm cross-links between docs resolve to correct Storybook paths

PR readiness check

  • PR should have one of the following labels:
    • Feature 🎁, Breaking Change 💣, Bug 🐛, Documentation 📝, Maintenance 🔨.
  • PR title follows the Conventional Commits format.
  • The code follows the appropriate code standards
  • All packages define the required scripts in package.json:
    • All packages: check, check:fix, and test.
    • Packages with build steps: build to build the package for development or distribution, build:all to build all artifacts.

Screenshots

N/A — documentation-only change, no visual component changes.

…y, and cascade layers

Add 10 new MDX documentation files following the Diátaxis framework:

Explanations:
- GridSystem.mdx: why responsive vs intrinsic, modifier pattern, subgrid
- SpacingScale.mdx: 8px base unit, rem rationale, baseline grid

How-to guides:
- HowToUseResponsiveGrid.mdx: breakpoint-driven column layouts
- HowToUseIntrinsicGrid.mdx: fluid content-driven layouts
- HowToForceTheme.mdx: dark/light subtree override
- HowToDebugTokens.mdx: DevTools token tracing
- HowToAlignBaseline.mdx: baseline grid alignment

Tutorial:
- TutorialFirstGrid.mdx: guided dashboard layout build

Reference:
- GridReference.mdx: all grid classes, custom properties, breakpoints
- CascadeLayersReference.mdx: 5-layer cascade architecture with channels

Also adds SpacingScale and TypographyScale story exports to
Tokens.stories.tsx and restructures the hub Introduction.mdx to
surface the Diátaxis navigation map.
@advl advl added the Documentation 📝 Improvements or additions to documentation label Mar 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Documentation 📝 Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant