Summary
DESIGN.md has the potential to become foundational infrastructure for how AI coding agents produce UI. That makes it significantly different from a typical design tooling project — and it places a corresponding responsibility on the format specification itself to model accessible design practices.
This issue is not a criticism of what has been built. It is a request, rooted in optimism about this project's reach, to treat accessibility as a first-class citizen in the format spec — not an afterthought or a downstream implementation concern.
The core concern: accessibility cannot be delegated to the agent
The current design of DESIGN.md is premised on the idea that a well-described visual identity, handed to an AI agent, will produce correct UI. For visual styling alone this may hold. But accessibility is not a visual-layer concern exclusively — it involves semantics, interaction patterns, state communication, and reading order. The format currently provides no guidance in these areas.
More specifically: a developer who authors a compliant DESIGN.md file today can reasonably feel they have "done their part." This creates a false sense of assurance. The agent receives a color palette and typography scale and is expected to produce accessible UI — but nothing in the format tells the agent what accessible UI looks like, nor does the linter verify it.
Given Google's position in the ecosystem and the scale at which this format is likely to be adopted, design decisions made here will propagate widely. This is precisely why the format should lead on accessibility — not follow.
Specific issues
1. Contrast checking covers only explicitly-defined component pairs
The contrast-ratio lint rule only fires when both backgroundColor and textColor are defined on a components entry. Most real-world DESIGN.md files will define color tokens without fully specifying every component — leaving the majority of color combinations unverified. A file can pass the linter with zero contrast warnings while containing combinations that fail WCAG at implementation time.
Request: Expand contrast validation beyond component pairs, or at minimum surface a clear warning when color tokens exist but no component-level contrast has been verified.
2. WCAG AA should be a baseline, not a target
The linter checks against WCAG AA (4.5:1), which is the right minimum — but the format should make clear that AA is a floor, not a destination. There is currently no path toward AAA (7:1) for body text, nor any mechanism for non-text contrast (WCAG SC 1.4.11, minimum 3:1 for UI components and graphical objects). Borders, icons, form control boundaries, and focus indicators are entirely outside the linter's scope. Treating AA as sufficient risks normalizing the minimum as the goal, particularly when the format is consumed at scale by AI agents that cannot exercise judgment about context or user needs.
Request: Add a non-text contrast rule. Consider surfacing AAA as an aspirational target in lint output, and add language in the spec that frames WCAG AA as a minimum requirement rather than a design objective.
3. Color values are restricted to sRGB hex
The spec defines Color as "#" + hex in the sRGB color space. Wide-gamut displays (P3, Rec. 2020) are now mainstream on iOS, macOS, and many Android devices. Constraining tokens to sRGB silently discards color fidelity on these devices and forecloses future-proof contrast computation in wider color spaces.
Request: Allow oklch(), color(display-p3 ...), and other modern CSS color syntaxes in the Color type.
4. on-* counterpart tokens are non-normative
The recommended token names include on-surface, but foreground/background pairing is listed as non-normative guidance only. Without a normative requirement to define a foreground token for each background token, AI agents will guess — and guesses will fail.
Request: Make paired foreground tokens (e.g., on-primary, on-secondary) a normative requirement when their corresponding background token is defined.
5. Focus indicator tokens exist but need careful guardrails
The component property token set currently has no way to express focus ring appearance, which matters because focusRingColor, focusRingWidth, and related properties genuinely need to reflect the surrounding content colors to ensure sufficient contrast. However, focus indicators are also among the most commonly misused design elements: they are frequently overridden for aesthetic reasons in ways that harm keyboard and switch-device users. The risk with adding these tokens is that DESIGN.md — and the agents consuming it — may treat focus styling as a routine visual design decision, rather than a safety-critical accessibility feature.
Request: Add focusRingColor, focusRingWidth, and focusRingOffset as component property tokens, with explicit guidance in the spec that:
- the browser default focus indicator should be preserved unless there is a specific, justified reason to override it;
- any custom focus indicator must meet WCAG SC 2.4.11 (Focus Appearance, AA) — minimum area, minimum contrast of 3:1 against adjacent colors;
- agents should be instructed to treat absence of focus tokens as "preserve the default," never as "remove the indicator."
6. Elevation and depth have no high-contrast fallback model
The spec describes elevation through shadows and tonal layering, but provides no guidance on how these should degrade in Windows High Contrast Mode (Forced Colors) or similar accessibility modes. Agents generating shadow-only depth cues will produce UIs that lose all visual hierarchy in these environments.
Request: Add guidance in the Elevation & Depth section on providing border- or outline-based fallbacks. Reference the CSS forced-colors media query.
7. No minimum font size constraint
The typography schema accepts any fontSize value. The spec example itself defines label-caps at 12px. Small text at this size is already marginal in English; in CJK scripts it is genuinely inaccessible. There is no lint rule enforcing a minimum.
Request: Add a lint warning for fontSize values below 14px (or 16px for body-level roles), with a note about CJK considerations.
8. Negative letterSpacing passes without warning
The h1 example includes letterSpacing: -0.02em. Aggressive negative tracking can cause character collision and impair readability, particularly for users with dyslexia or low vision. The linter does not flag any letterSpacing value.
Request: Add a lint warning for letterSpacing values below a reasonable threshold (e.g., -0.05em).
9. lineHeight: 1 is incompatible with WCAG 1.4.12 Text Spacing
A lineHeight of 1 (as seen in the label-caps example) means text cannot be re-spaced to meet user overrides required by WCAG SC 1.4.12 (Text Spacing). Content must not lose functionality when line height is increased to at least 1.5× the font size.
Request: Add a lint warning for lineHeight values below 1.5 on tokens used in body or label roles. Document the 1.4.12 requirement in the Typography section.
10. Disabled and interactive states have no accessibility-aware token model
The spec allows variant components (e.g., button-primary-hover) but provides no normative guidance on how states like disabled, aria-selected, aria-expanded, or aria-pressed should be expressed. Disabled states expressed only through reduced opacity commonly fail non-text contrast requirements.
Request: Add guidance and/or token conventions for interactive states, with a note that disabled states must meet non-text contrast requirements (1.4.11) and must not rely solely on color or opacity.
What would "accessibility as a first-class citizen" look like?
- A normative
## Accessibility section in the spec, analogous to ## Colors or ## Typography
- Required token pairs for foreground/background combinations
- Focus indicator tokens in the component property set, with clear guidance on when and how to use them
- Lint rules covering non-text contrast, minimum font size, line height, and focus ring presence
- Explicit guidance on Forced Colors / High Contrast Mode degradation
- A statement in the README that DESIGN.md-conformant files are expected to produce WCAG 2.2 AA accessible UI
Offered contribution
I would be glad to help draft the accessibility section of the spec, propose lint rule additions, or review any pull requests in this area. Please let me know if a more focused issue per concern would be preferred over this consolidated report.
Thank you for building this — and for considering these concerns.
Summary
DESIGN.md has the potential to become foundational infrastructure for how AI coding agents produce UI. That makes it significantly different from a typical design tooling project — and it places a corresponding responsibility on the format specification itself to model accessible design practices.
This issue is not a criticism of what has been built. It is a request, rooted in optimism about this project's reach, to treat accessibility as a first-class citizen in the format spec — not an afterthought or a downstream implementation concern.
The core concern: accessibility cannot be delegated to the agent
The current design of DESIGN.md is premised on the idea that a well-described visual identity, handed to an AI agent, will produce correct UI. For visual styling alone this may hold. But accessibility is not a visual-layer concern exclusively — it involves semantics, interaction patterns, state communication, and reading order. The format currently provides no guidance in these areas.
More specifically: a developer who authors a compliant DESIGN.md file today can reasonably feel they have "done their part." This creates a false sense of assurance. The agent receives a color palette and typography scale and is expected to produce accessible UI — but nothing in the format tells the agent what accessible UI looks like, nor does the linter verify it.
Given Google's position in the ecosystem and the scale at which this format is likely to be adopted, design decisions made here will propagate widely. This is precisely why the format should lead on accessibility — not follow.
Specific issues
1. Contrast checking covers only explicitly-defined component pairs
The
contrast-ratiolint rule only fires when bothbackgroundColorandtextColorare defined on acomponentsentry. Most real-world DESIGN.md files will define color tokens without fully specifying every component — leaving the majority of color combinations unverified. A file can pass the linter with zero contrast warnings while containing combinations that fail WCAG at implementation time.Request: Expand contrast validation beyond component pairs, or at minimum surface a clear warning when color tokens exist but no component-level contrast has been verified.
2. WCAG AA should be a baseline, not a target
The linter checks against WCAG AA (4.5:1), which is the right minimum — but the format should make clear that AA is a floor, not a destination. There is currently no path toward AAA (7:1) for body text, nor any mechanism for non-text contrast (WCAG SC 1.4.11, minimum 3:1 for UI components and graphical objects). Borders, icons, form control boundaries, and focus indicators are entirely outside the linter's scope. Treating AA as sufficient risks normalizing the minimum as the goal, particularly when the format is consumed at scale by AI agents that cannot exercise judgment about context or user needs.
Request: Add a non-text contrast rule. Consider surfacing AAA as an aspirational target in lint output, and add language in the spec that frames WCAG AA as a minimum requirement rather than a design objective.
3. Color values are restricted to sRGB hex
The spec defines
Coloras"#" + hex in the sRGB color space. Wide-gamut displays (P3, Rec. 2020) are now mainstream on iOS, macOS, and many Android devices. Constraining tokens to sRGB silently discards color fidelity on these devices and forecloses future-proof contrast computation in wider color spaces.Request: Allow
oklch(),color(display-p3 ...), and other modern CSS color syntaxes in the Color type.4.
on-*counterpart tokens are non-normativeThe recommended token names include
on-surface, but foreground/background pairing is listed as non-normative guidance only. Without a normative requirement to define a foreground token for each background token, AI agents will guess — and guesses will fail.Request: Make paired foreground tokens (e.g.,
on-primary,on-secondary) a normative requirement when their corresponding background token is defined.5. Focus indicator tokens exist but need careful guardrails
The component property token set currently has no way to express focus ring appearance, which matters because
focusRingColor,focusRingWidth, and related properties genuinely need to reflect the surrounding content colors to ensure sufficient contrast. However, focus indicators are also among the most commonly misused design elements: they are frequently overridden for aesthetic reasons in ways that harm keyboard and switch-device users. The risk with adding these tokens is that DESIGN.md — and the agents consuming it — may treat focus styling as a routine visual design decision, rather than a safety-critical accessibility feature.Request: Add
focusRingColor,focusRingWidth, andfocusRingOffsetas component property tokens, with explicit guidance in the spec that:6. Elevation and depth have no high-contrast fallback model
The spec describes elevation through shadows and tonal layering, but provides no guidance on how these should degrade in Windows High Contrast Mode (Forced Colors) or similar accessibility modes. Agents generating shadow-only depth cues will produce UIs that lose all visual hierarchy in these environments.
Request: Add guidance in the Elevation & Depth section on providing border- or outline-based fallbacks. Reference the CSS
forced-colorsmedia query.7. No minimum font size constraint
The typography schema accepts any
fontSizevalue. The spec example itself defineslabel-capsat12px. Small text at this size is already marginal in English; in CJK scripts it is genuinely inaccessible. There is no lint rule enforcing a minimum.Request: Add a lint warning for
fontSizevalues below14px(or16pxfor body-level roles), with a note about CJK considerations.8. Negative
letterSpacingpasses without warningThe h1 example includes
letterSpacing: -0.02em. Aggressive negative tracking can cause character collision and impair readability, particularly for users with dyslexia or low vision. The linter does not flag any letterSpacing value.Request: Add a lint warning for
letterSpacingvalues below a reasonable threshold (e.g.,-0.05em).9.
lineHeight: 1is incompatible with WCAG 1.4.12 Text SpacingA
lineHeightof1(as seen in thelabel-capsexample) means text cannot be re-spaced to meet user overrides required by WCAG SC 1.4.12 (Text Spacing). Content must not lose functionality when line height is increased to at least 1.5× the font size.Request: Add a lint warning for
lineHeightvalues below1.5on tokens used in body or label roles. Document the 1.4.12 requirement in the Typography section.10. Disabled and interactive states have no accessibility-aware token model
The spec allows variant components (e.g.,
button-primary-hover) but provides no normative guidance on how states likedisabled,aria-selected,aria-expanded, oraria-pressedshould be expressed. Disabled states expressed only through reduced opacity commonly fail non-text contrast requirements.Request: Add guidance and/or token conventions for interactive states, with a note that disabled states must meet non-text contrast requirements (1.4.11) and must not rely solely on color or opacity.
What would "accessibility as a first-class citizen" look like?
## Accessibilitysection in the spec, analogous to## Colorsor## TypographyOffered contribution
I would be glad to help draft the accessibility section of the spec, propose lint rule additions, or review any pull requests in this area. Please let me know if a more focused issue per concern would be preferred over this consolidated report.
Thank you for building this — and for considering these concerns.