velofy DESIGN.md profile, draft 0.1

This is a proposal, not a package, linter, or Model Context Protocol (MCP) server. It extends the Google Labs DESIGN.md convention rather than replacing it. The base convention is useful because it pairs structured frontmatter with an eight-section Markdown body. It lacks two things: a portable token shape, and a clear statement of where each value came from.

So the profile keeps the body used by Google Labs’ DESIGN.md, Design Extractor, and designmd.supply. It adopts the $type, $value, and $description token shape associated with the Design Tokens Community Group (DTCG) format. And it makes provenance mandatory.

First principles

A design description handed to an agent carries four kinds of information, and each needs a different form.

Values. A color, a size, a font family. These are exact and checkable, so they belong in structured tokens with a declared type.
Relations. One token defined as another (an alias), or a text color meant for a given surface. A program can check these too: an alias resolves or it does not, and a text and surface pair meets a contrast threshold or it does not.
Rationale. When to use a value, what to avoid, and why. A parser cannot hold this, so it belongs in prose that people and agents both read.
Origin. Whether a value was read from source code, scraped from a rendered page, or inferred by a model. Nothing in the value reveals this. #1A1C1E looks the same whether it was measured or guessed.

The last point drives the profile. A reader cannot tell an observed value from an inferred one unless the file says so, so provenance has to be a required field, not an optional note.

A linter has a matching limit. It can check values, relations, and the presence of provenance. It cannot check whether the values match the product they describe. That is why the lint rules below stop at structure, references, and contrast.

Profile shape

The frontmatter is YAML, a plain-text data format. Token groups may be nested. Every leaf token has $value; $type and $description should appear where they make the token unambiguous. Aliases use the existing {path.to.token} convention.

---
version: "0.1-draft"
name: example-system
description: A short description of the visual system.
provenance:
  source_url: https://example.com/
  extraction_method: manual
  confidence:
    colors: high
    typography: high
    layout: medium
    components: medium
  generated_by: named person or tool
  generated_at: "2026-09-23"
tokens:
  color:
    primary:
      $type: color
      $value: "#1A1C1E"
      $description: Primary interactive color.
  typography:
    body:
      fontFamily:
        $type: fontFamily
        $value: "Public Sans"
      fontSize:
        $type: dimension
        $value: "1rem"
---

source_url, extraction_method, confidence, generated_by, and generated_at are required. extraction_method is one of manual, LLM-inferred, or DOM-scraped: written by hand from source, inferred by a large language model (LLM), or read from a rendered page’s Document Object Model (DOM). Confidence can be a number from 0 to 1 or a section-level low, medium, or high label. A profile should say what it knows, not imply that an interpretation is source truth.

The eight sections

The body retains the order that has emerged across current DESIGN.md implementations:

Overview
Colors
Typography
Layout & Spacing
Elevation & Depth
Shapes
Components
Do’s and Don’ts

The frontmatter is the compact layer for machines. The body explains use, hierarchy, exceptions, and choices that a single color or spacing value cannot convey. It stays readable without a parser.

Planned lint rules

These are proposed rules for a future linter. They describe intent only. No @velofy/design-md package exists today.

Require a frontmatter block with version, name, description, provenance, and tokens.
Require non-empty source_url, extraction_method, confidence, generated_by, and generated_at inside provenance.
Accept only manual, LLM-inferred, or DOM-scraped as extraction_method.
Require $value on each leaf token, and a valid DTCG-shaped value for its declared $type where the type is present.
Resolve every {path.to.token} alias and report unresolved references.
Require the eight body sections in their stated order.
Check declared text and surface pairs for Web Content Accessibility Guidelines (WCAG) AA contrast, following the direction of the Google Labs command-line interface (CLI).
Treat any future --export dtcg and --export tailwind output as an explicit transformation. It is not a claim that the Markdown body converts to machine-readable form without loss.

Worked example: velofy.co

This is velofy.co’s own profile as of 2026-09-23, derived by hand from the checked-in Cascading Style Sheets (CSS). It is a source-level record, not an extraction. Each token names its CSS source file, so an agent or reviewer can go back to the declaration.

The site has been redesigned since. As of 2026-10-24, the live profile at /DESIGN.md is version 0.4-draft. It replaces the warm paper, Manrope, and IBM Plex Mono values below with a black ground, Switzer, and Fragment Mono. The example still shows the profile’s shape, but its values record the site as it was, not as it is.

---
version: "0.1-draft"
name: velofy.co
description: Warm-paper editorial site for an open source applied AI lab.
provenance:
  source_url: https://velofy.co/
  extraction_method: manual
  confidence:
    colors: high
    typography: high
    layout: high
    components: high
  generated_by: velofy editorial team
  generated_at: "2026-09-23"
tokens:
  color:
    paper:
      $type: color
      $value: "#f7f6f2"
      $description: Page background. Source: sites/velofy/src/styles/site.css.
    ink:
      $type: color
      $value: "#232321"
      $description: Primary text and dark surface. Source: sites/velofy/src/styles/site.css.
    muted:
      $type: color
      $value: "#66665f"
      $description: Secondary text. Source: sites/velofy/src/styles/site.css.
    line:
      $type: color
      $value: "#d9d7d0"
      $description: Borders and dividers. Source: sites/velofy/src/styles/site.css.
    accent:
      $type: color
      $value: "#45453f"
      $description: Link hover and focus color. Source: sites/velofy/src/styles/site.css.
    soft:
      $type: color
      $value: "#eeece5"
      $description: Soft surface. Source: sites/velofy/src/styles/site.css.
    lime:
      $type: color
      $value: "#e1ddd2"
      $description: Selection and footer accent. Source: sites/velofy/src/styles/site.css.
  typography:
    sans:
      $type: fontFamily
      $value: "Manrope Variable, Arial, sans-serif"
      $description: Base family. Source: sites/velofy/src/styles/site.css.
    mono:
      $type: fontFamily
      $value: "IBM Plex Mono, monospace"
      $description: Eyebrows and metadata. Source: sites/velofy/src/styles/site.css.
    prose:
      fontSize:
        $type: dimension
        $value: "1.075rem"
        $description: Article copy size. Source: shared/prose.css.
      lineHeight:
        $type: number
        $value: 1.8
        $description: Article copy leading. Source: shared/prose.css.
  spacing:
    page:
      $type: dimension
      $value: "48px"
      $description: Desktop page inset. Source: sites/velofy/src/styles/site.css.
    tablet:
      $type: dimension
      $value: "28px"
      $description: Tablet page inset. Source: sites/velofy/src/styles/site.css.
    mobile:
      $type: dimension
      $value: "22px"
      $description: Mobile page inset. Source: sites/velofy/src/styles/site.css.
  radius:
    control:
      $type: dimension
      $value: "2px"
      $description: Primary link radius. Source: sites/velofy/src/styles/site.css.
    code:
      $type: dimension
      $value: "3px"
      $description: Inline-code and preformatted block radius. Source: shared/prose.css.
---

Overview

Velofy uses a warm paper field, near-black ink, thin stone-colored rules, and a large restrained sans-serif hierarchy. The site is editorial rather than application-like. Metadata is compact and monospaced; long-form copy gets more line-height than the surrounding navigation.

Colors

Use paper for the page, ink for primary text and dark surfaces, and line for separation. muted carries supporting copy. lime is a quiet highlight rather than an action color. These values are declared in sites/velofy/src/styles/site.css.

Typography

The base family is Manrope Variable, with Arial and generic sans-serif fallbacks. IBM Plex Mono marks system-like labels, dates, and navigation metadata. Article prose is 1.075rem with 1.8 line-height, from shared/prose.css.

Layout & Spacing

The desktop page inset is 48px, reduced to 28px at the tablet breakpoint and 22px on small screens. Article content is centered with a reading column and a separate table of contents. Those layout values are declared in sites/velofy/src/styles/site.css and shared/prose.css.

Elevation & Depth

No shadow token is declared in the checked CSS. Depth comes from paper versus ink surfaces, thin borders, and change in type scale. Do not add shadows as a substitute for hierarchy without a deliberate source change.

Shapes

Controls use 2px rounding. Inline code and code blocks use 3px. Most structural elements are square and separated by rules, not pills or floating cards.

Components

The header, page heading, catalog rows, article shell, prose, and footer are the visible structural components. Preserve the reading column and its table of contents rather than placing dense interface controls into article pages.

Do’s and Don’ts

Do keep the paper, ink, and rule system quiet. Do use mono text for labels and metadata. Do preserve the responsive 48px, 28px, and 22px page insets. Don’t introduce a new accent palette, broad corner rounding, or unrecorded shadows. Don’t present this manually derived profile as an extraction.

What velofy is doing next

Velofy keeps its profile in the repository and publishes it at /DESIGN.md as a small public example. That file has already moved past this draft as the site changed. Keeping it in the same repository as the CSS it describes is what makes that change visible. Any future linter, token export, or agent interface will be described as a proposal until it exists and can be used.

Source ↗

← All design-engineering entries