google-labs-code / google-labs-code/design.md

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

Open
#154 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
28k
Forks
2.3k
PR merge metrics
No merged PRs in 30d

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the DESIGN.md schema, the design.md lint command, and exporter paths; run the existing lint flow to see how tokens are parsed and validated. Compare the requested breakpoint, responsive, and units shapes with current behavior, including how intentional px exceptions should be represented. Done means the primitives are defined in the spec and linting and exporters enforce the stated policies.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript, yaml
Domain
design, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.