docs(spec): define responsive theme adaptations

[imdreamrunner]

Why

Themes need opt-in adaptations for environmental conditions without a second theme, handwritten media-query CSS, or React styling state.

Accepted contract

• adaptations, not responsive or responsiveness.
• widthBreakpoints, not generic breakpoints.
• Named {when, value} rules, not positional tuples.
• Nested width: {from, below}, not flat minWidth / maxWidth.
• Fields in when are ANDed.
• Width points mark tier starts; from is inclusive and below is exclusive.
• Rules follow authored cascade order; later matching writes win.
• Source and built themes preserve equivalent adaptation data for extends.
• Breakpoint configuration alone emits no CSS.

defineTheme({
  adaptations: {
    widthBreakpoints: {
      sm: 640,
      md: 768,
      lg: 1024,
      xl: 1280,
      '2xl': 1536,
    },
    rules: [
      {
        when: {
          width: {from: 'lg', below: 'xl'},
          pointer: 'coarse',
          contrast: 'more',
        },
        value: {
          components: {/* overrides */},
        },
      },
    ],
  },
});

Approval

Cindy approved the complete contract at adf1b531b2. This update records that decision as authority: current, phase: accepted, approved_by: cixzhang, with no open questions.

Because the spec-owner gate binds approval to the exact commit, this metadata-only promotion invalidates the previous head approval and needs one final approval on the promoted head.

Relationship to #5543

#5543's public tier API is superseded by this accepted contract and must not land as-is. Its value resolver, explicit-value preservation, CSS generation/build parity, and extension metadata remain useful implementation evidence.

Risk

Knowledge only. No runtime, package, or consumer behavior changes. The AppShell equality change is identified as breaking for the later implementation.

Validation

• pnpm check:knowledge -- --base origin/main
• pnpm check:repo
• Prettier, diff, stale-vocabulary, and public-content checks

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 2, 2026 8:51pm UTC

[cixzhang]

Theme authors who need one coarse-pointer rule across all widths would still have to duplicate it across manufactured width tiers, although the intent promises width or pointer adaptation.

Thanks—fixed tiers, sparse matching, inheritance, pins, and compiler parity are much clearer. Before this draft is ready:

• Make the pointer choice explicit: can pointer rules stand alone, and are conditions nested under width or represented as a flat, closed model?
• The built-theme requirement preselects always-on metadata even though the draft leaves that bundle-cost choice open. State both compatibility outcomes.
• Keep #5543 as evidence, but move branch-specific rollout steps into an implementation plan so this specification survives a replacement implementation.

[Reviewed by Robohands]

[cixzhang]

Visible review summary — suggestions for Ivor to resolve, not a prescribed API rewrite.

The full three-option exploration is on the implementation PR: #5543 (comment)

Before this draft can become current, it should settle three contract questions:

• Condition shape: can pointer rules stand alone across all widths, and are width/pointer combinations represented by a flat closed model or by nesting one axis under another?
• Built-theme compatibility: describe both outcomes for condition metadata—retained for runtime inspection versus compiled away—rather than preselecting permanent bundle cost while the choice remains open.
• Durable rollout: keep feat(theme): ordered environmental adaptations in defineTheme #5543 as implementation evidence, but move branch-specific migration steps out of the specification so a replacement compiler can satisfy the same contract.

My exploration leans toward a flat, closed adaptations model because it can express width-only, pointer-only, and combined rules without promising arbitrary CSS media syntax. That direction still needs canonical identity, precedence, conflict, inheritance, and diagnostics before it is dependable. @imdreamrunner owns the final shape after weighing those guarantees against implementation cost.