Skip to content

Add optional first-class responsive tokens and unit-policy linting #154

Description

@rxdt

Requested Feature

Add first-class responsive design primitives to DESIGN.md so agents can generate responsive UIs from the spec instead of inventing breakpoints, units, and layout behavior.

Problem

DESIGN.md currently captures visual identity tokens well, but responsive behavior mostly has to live in prose. Prose helps humans, but agents and design.md lint cannot reliably enforce it. A project may want to express rules like:

  • use mobile-first layout
  • use content-driven breakpoints
  • use em media queries, not px
  • use relative units for spacing, layout, and type
  • allow px only for explicit exceptions such as hairline borders

Why

Coding agents are primary consumers of DESIGN.md. Without responsive primitives, agents either:

  • invent breakpoint values
  • hardcode px breakpoints
  • ignore responsiveness
  • rely on prose that cannot be linted
  • drift from project lint rules
    Responsive unit policy fits the same model: encode the rule once, then let the linter and exporters enforce it. This is especially useful for accessibility and maintainability. px font sizes and px breakpoints can conflict with user scaling and responsive policy, while px may still be valid for narrow intentional cases.

Schema

breakpoints:
  compact: 40em
  wide: 64em

responsive:
  strategy: mobile-first
  breakpoint-policy: content-driven
  media-query-unit: em

units:
  breakpoints: [em]
  spacing: [rem]
  rounded: [rem]
  typography:
    fontSize: [rem, em]
  components:
    padding: [rem]
    width: [rem, em, "%"]
    height: [rem, em]

typography:
  body:
    fontSize: 14px # invalid if typography.fontSize only allows rem/em

breakpoints:
  wide: 1040px # invalid if breakpoints only allows em

units:
  borderWidth: [px] # projects should be able to use px  without allowing px everywhere.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions