Design systems

What a design system is

A closed JSON document (format: "texuli/design-system"): identity, then optional sections for color, typography, shape, space, elevation, surface, motion, layout, icons, component defaults, assets, voice, accessibility targets and variants. Lengths are numbers, colors are values, and nothing is raw CSS. The smallest valid document is a brand color:

{
  "format": "texuli/design-system",
  "formatVersion": 1,
  "id": "harborline",
  "version": "1.0.0",
  "name": "Harborline",
  "color": { "brand": { "seed": "#0e7490" } }
}

1. Validate: the spec checks the closed shape and answers with stable codes and JSON paths, so a person or an agent repairs a document from the code alone.
2. Compile: concrete --tx-* variables per mode. Text pairs meet the declared target (AA 4.5:1 or AAA 7:1), the focus ring 3:1 at 2 px or wider, and controls the declared target size; the compiler refuses only what pinned colors make impossible.
3. Apply or emit: DesignSystemProvider or applyDesignSystem on any element, designSystemStyle for server HTML, and emitters for CSS, a Tailwind preset, DTCG, Tokens Studio, email, PDF, DOCX, PPTX, canvas and Kotlin tokens.

Three brands, four surfaces

Three fictional brands from the repository's examples/design-systems folder, compiled when this page was built and applied through DesignSystemProvider. Each surface below is the same markup and the same content; only the design system changes. The previews show light mode, and they ship no JavaScript.

• Quillmark

  [email protected] · seed #b4532a

  A literary magazine: warm paper neutrals, a terracotta seed, a serif body.

  A brand seed with a warm neutral, type families and roles, flat surfaces, outline buttons by default.

  The document for Quillmark · texuli://design-system/quillmark

• Ledgerline

  [email protected] · extends texuli:slate-masthead · seed #1d4ed8

  A finance back office: dense spacing, 14 px base type, crisp edges.

  extends: "texuli:slate-masthead", small buttons by default, a high-contrast variant held to AAA.

  The document for Ledgerline · texuli://design-system/ledgerline

• Tumbletown

  [email protected] · seed #d6336c

  A family game studio: 20 px radius, pill buttons, expressive motion.

  The brand pink pinned exactly, 44 px targets (control heights lifted), a glow focus ring.

  The document for Tumbletown · texuli://design-system/tumbletown

Brand fonts are named in each document but not loaded on this site, so each preview falls back along its font stack.

Conformance

Every number below is read from the compiler's report when this page was built, through checkDesignSystem: the static half of texuli ds check (the spec's validation, the extends chain, the compile of the document and of its high-contrast variant, then the guarantees checked again over the compiled variables).

Pairs are text on every surface role (4.5:1 at AA, 7:1 at AAA), strong borders and inputs (3:1), and the focus ring against the page and the surface (3:1). Control heights are the control sizes held to the brand's target size. A solver move is a color or a size the compiler changed to meet a guarantee, per mode: Tumbletown's are its control heights lifted to its 44 px target and the text color on its pinned pink in dark mode.

Run the same check on a brand, or on your own document:

texuli ds check examples/design-systems/quillmark.json
texuli ds check examples/design-systems/ledgerline.json
texuli ds check examples/design-systems/tumbletown.json

--render also paints every agent-emittable catalog component under the design system in headless Chromium and checks axe, the painted contrast of every pair and colors that ignore the design system; CI runs it on these three brands. Details: texuli ds check.

Start one

texuli ds init brand.ds.json --name Harborline       # a starter document
texuli ds validate brand.ds.json                     # stable codes and JSON paths
texuli ds compile brand.ds.json --format css --out dist/brand.css
texuli ds preview brand.ds.json --format svg --out review/brand.svg
texuli ds diff brand.ds.json next.ds.json            # changed variables, contrast regressions
texuli ds import tokens/brand.tokens.json --from dtcg --out imported.ds.json
texuli ds export brand.ds.json --format dtcg --out tokens/brand.tokens.json
texuli ds check brand.ds.json --render               # the conformance check