Foundations
The foundations section documents the v1 design-system building blocks that are published for consumers today.
These pages translate the repository token source into the supported runtime contract: stable token names, the supported stylesheet entrypoint, accessibility guarantees, and the boundaries between stable and deferred surfaces.
Current scope
The current public foundations guidance covers:
- colors
- typography
- spacing and layout
- corners, effects, and overlays
- desktop, mobile, and theme modes
Stable runtime contract
- Stable stylesheet:
@jflamb/fdic-ds-tokens/styles.css - Stable token prefixes:
--fdic-color-*,--fdic-spacing-*,--fdic-corner-radius-*,--fdic-layout-*,--fdic-shadow-*,--fdic-gradient-*,--fdic-font-*,--fdic-line-height-*,--fdic-letter-spacing-*, and--fdic-heading-padding-* - Stable component override prefix:
--fd-*only when a component page documents the token explicitly - Stable data export:
@jflamb/fdic-ds-tokens/fdic.tokens.json - Supported component stylesheet:
@jflamb/fdic-ds-components/styles.css
These pages explain how to use that contract safely and where the public API intentionally stops.
The Page Shell page is the canonical responsive section-alignment contract for shell components and top-level page sections.
The Spacing and Layout page is the canonical spacing and layout token contract. Other public docs should defer to these foundations pages rather than restating layout tokens or implementation details independently.
The Patterns guide explains when to use components, composition patterns, and page recipes. The Composition Patterns page documents the small stable layout-class surface that CMS consumers can use when tokens alone are not enough.
Deferred from v1
- Responsive token bundles for separate desktop and mobile modes are not part of the public runtime contract yet.
- Broad component token surfaces are not part of the public contract yet. Only component-level CSS custom properties explicitly documented on component pages are supported.
- Any backward-compatible alias entrypoints are compatibility affordances, not the preferred path for new consumers.
Foundation pages
Semantics before hex values
Document brand, text, background, border, and status use in a way that supports trust and accessibility.
Readable hierarchy
Capture type families, scale, and rhythm with enough context to support plain-language government content.
Constraints that aid comprehension
Explain spacing, widths, and responsive differences as usability rules, not just measurements.
- Colors
- Customization
- Page Shell
- Typography
- Spacing and Layout
- Composition Patterns
- Surfaces and Effects
- Modes and Responsiveness
Internal reference
For the fuller source inventory and implementation notes, including historical Figma export labels that are not part of the public API, see docs/architecture/token-inventory.md in the repository.