Foundations

The NYS Design System is more than a collection of components. It is a set of shared decisions — about color, spacing, typography, accessibility, and interaction — that make those components consistent, themeable, and predictable across every New York State agency.

Foundations are where those decisions live. They define how components get their styles, how themes change an entire site's appearance without touching component code, how forms validate and submit, and how accessibility is built in from the start.

Whether you are building a new application with NYSDS components or integrating the design system's styles into an existing site, understanding these foundations will help you work with the system instead of around it.

System Foundations

How the design system is built — the token layers, styling framework, theming system, component architecture, and accessibility standards that power everything.

Accessibility
How the design system supports WCAG 2.2 AA compliance, with guidance for developers, content creators, and leadership.
Styles Framework
The @nysds/styles CSS package — design tokens as custom properties, a CSS reset, typography classes, and layout utilities.
Agency Themes
Apply agency-specific color palettes with a single attribute — build once, switch themes, and every component updates automatically.
Design Tokens
The shared language of colors, spacing, and typography values — how primitive, semantic, and theme tokens connect design decisions to code.
How Components Work
Web components, shadow DOM, slots, CSS custom properties, and the patterns you need to use NYSDS components effectively.

Implementation Guides

Practical references for building interfaces with the design system — typography, form patterns, layout utilities, and the broader design process.

Design
Where the design system fits in the broader UX process — from strategy and scope to the interface layer.
Typography
Core typefaces, typography tokens, font installation, and utility classes for consistent, accessible type across your application.
Form Patterns
Form association, validation strategies, event handling, and submission patterns that work across all NYSDS form components.
Utilities
Layout grid, flexbox, spacing, display, and responsive utility classes for rapid, consistent page layout.

Reference

Need to look up a specific token value or component API? These are also always available in the main navigation.

Token Browser
Browse all design tokens — colors, spacing, typography, and theme values — with an interactive theme switcher.
Component Catalog
All 27 NYSDS components — properties, events, accessibility details, and copy-paste examples.

Edit this page on GitHub (Permissions required)

Last updated: May 20, 2026