feat: tooling to generate canonical DESIGN.md

[peter-gy]

Summary

Adds tooling for generating canonical root DESIGN.md (https://github.com/google-labs-code/design.md) from marimo frontend design tokens so coding agents have a default visual identity to read before generating UI around notebooks, widgets, dashboards, reports, and static exports.

Details

The DESIGN.md frontmatter is generated from existing frontend sources to avoid drift:

• CSS design tokens from marimo stylesheets
• typography, radius, and spacing values from frontend config
• selected layout defaults used by cells, outputs, grids, and editors

To access these values from the codebase, we use a deno script (via uv tool run deno / uvx deno) with

• npm:@babel/parser to parse config files for token values that are not available as CSS
• npm:culori + npm:postcss and friends to normalize CSS colors, declarations, variables, functions, and calc() values
• npm:tailwindcss to access default scales and values

The PR also adds tooling to lint DESIGN.md with pnpm --silent dlx @google/design.md@0.1.1 and to check if it needs to be regenerated.

Effect

The following prompt passed to an image generation model (gpt-image-2)

given this design.md file create a wide board displaying all components and declared design system in light mode and dark mode.

{DESIGN.md contents pasted here}

yields:

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	May 22, 2026 1:05pm

[Copilot]

Pull request overview

Adds a Deno-based generator to produce a canonical root DESIGN.md from marimo frontend token sources, and wires generation + linting into local and CI workflows so the file stays in sync.

Changes:

• Added scripts/generate-design-md.ts to extract CSS variables + selected TS config/layout defaults and emit a DESIGN.md with YAML frontmatter.
• Added make design-md / make design-md-check targets, plus a dedicated CI workflow to enforce freshness and lint the artifact.
• Added a pre-commit hook to regenerate DESIGN.md when token inputs change.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/generate-design-md.ts	New Deno script that builds the DESIGN.md YAML frontmatter from CSS + TS sources and prints the generated markdown.
Makefile	Adds generation/check targets and a CI-friendly diff + lint step for DESIGN.md.
.pre-commit-config.yaml	Adds a local hook to regenerate DESIGN.md when upstream token sources change.
.github/workflows/test_design_md.yaml	New workflow that runs make design-md-check via pixi on PRs touching design/token sources.
DESIGN.md	New/updated generated artifact tracked in-repo (currently empty in this PR checkout).

[cubic-dev-ai]

2 issues found across 5 files

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant Hook as pre-commit Hook
    participant Gen as generate-design-md.ts (Deno)
    participant Parser as Babel Parser
    participant PostCSS as PostCSS + Culori
    participant TW as Tailwind Defaults
    participant Yaml as YAML serializer
    participant Repo as Repo filesystem
    participant CI as CI (GitHub Actions)
    participant Linter as @google/design.md linter

    Note over Dev,CI: DESIGN.md generation pipeline

    alt pre-commit trigger
        Dev->>Dev: edits source files (CSS, TS, CJS)
        Hook->>Gen: make design-md
        Gen->>Repo: read scripts/generate-design-md.ts
        Gen->>Repo: read frontend/src/css/globals.css
        Gen->>Repo: read frontend/src/css/app/App.css
        Gen->>Repo: read frontend/src/css/app/Cell.css
        Gen->>Repo: read frontend/src/core/config/config-schema.ts
        Gen->>Repo: read frontend/src/plugins/impl/data-editor/themes.ts
        Gen->>Repo: read frontend/src/components/editor/renderers/grid-layout/plugin.tsx
        Gen->>Repo: read frontend/tailwind.config.cjs
    end

    Note over Gen,Yaml: Parse CSS token values

    Gen->>PostCSS: parse CSS sources -> AST root
    PostCSS-->>Gen: CssRoot objects
    Gen->>Gen: walkDecls -> collect --* vars
    Gen->>PostCSS: resolveColorValue() -> light-dark(), var()
    PostCSS->>Culori: formatHex(parseColor(value))
    Culori-->>PostCSS: normalized hex string
    PostCSS-->>Gen: resolved color values

    Note over Gen,Yaml: Parse config files for non-CSS tokens

    Gen->>Parser: parse frontend/tailwind.config.cjs
    Parser-->>Gen: ObjectExpression AST
    Gen->>Gen: extract borderRadius, fontFamily, fontSize maps

    Gen->>Parser: parse frontend/src/core/config/config-schema.ts
    Parser-->>Gen: ObjectExpression AST
    Gen->>Gen: extract default widths (content-compact, content-medium, content-wide)

    Gen->>Parser: parse frontend/src/plugins/impl/data-editor/themes.ts
    Parser-->>Gen: ObjectExpression AST
    Gen->>Gen: extract accent color for data-grid-accent

    Gen->>Parser: parse frontend/src/components/editor/renderers/grid-layout/plugin.tsx
    Parser-->>Gen: ObjectExpression AST
    Gen->>Gen: extract grid settings (row height, columns)

    Note over Gen,Yaml: Assemble DESIGN.md frontmatter

    Gen->>TW: read defaultTheme for spacing, borderRadius, fontSize
    TW-->>Gen: default scales
    Gen->>Gen: build colors object (light/dark pairs)
    Gen->>Gen: build typography object (families, sizes, weights)
    Gen->>Gen: build rounded object (from CSS + Tailwind)
    Gen->>Gen: build spacing object (from Tailwind + config)
    Gen->>Gen: build components object (references to tokens)

    Gen->>Yaml: stringify() frontmatter
    Yaml-->>Gen: YAML string with token references
    Gen->>Gen: prepend generated comment + hand-authored body
    Gen-->>Repo: write DESIGN.md (via stdout redirect)

    Note over CI,Linter: CI validation

    CI->>CI: pixi run make design-md-check
    CI->>Gen: generate DESIGN.md to temp file
    CI->>CI: diff -u DESIGN.md temp (check for drift)
    alt drift detected
        CI-->>Dev: fail + "Run 'make design-md' to update"
    else no drift
        CI->>Linter: @google/design.md lint DESIGN.md
        Linter-->>CI: lint results
        CI-->>Dev: pass
    end

    Note over Dev,CI: DESIGN.md structure

    Note over Repo: YAML frontmatter:<br/>- colors (29 entries)<br/>- typography (7 entries)<br/>- rounded (7 entries)<br/>- spacing (10 entries)<br/>- components (7 entries)
    Note over Repo: Body sections:<br/>- Intent<br/>- Token Use<br/>- Brand Assets<br/>- Components guidance<br/>- UI Guidance<br/>- Motion

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

[Light2Dark]

awesome! non-blocking comment