Design system documentation Astro theme: token pages generated from DTCG, components and contribution guide, bilingual

This theme is for teams and designers who already have their design tokens and want to publish their design system documentation on their own site, in French and English, rather than in a hosted documentation service. It is built with Astro and reads your files in the DTCG 2025.10 format at build time: the colour, typography, spacing, radius and border, shadow and motion pages are generated from your tokens, with their light and dark values, their aliases, their CSS variables and the contrast of your colour pairs. You write the component pages, the guides (including the contribution guide) and the release notes in Markdown.

The built site sends no JavaScript to the browser. The theme does not automatically import the content of existing documentation: a guide explains how to move it over while keeping your old addresses.

• 7 page templates, in French and English: home, foundation page generated from the tokens, component index, component page, guide, release notes and bilingual not-found page.
• 6 foundation pages generated from your DTCG files: colours, typography, spacing, radius and borders, shadows, motion. Each token appears with its value in each context, its alias, its CSS variable and a preview. The demo home page shows 6 foundation cards.
• A complete component page: examples rendered with your tokens and their HTML code, anatomy, do and don’t, accessibility, tokens used with a link to their row, frequently asked questions. An unknown token path in a component page makes the build fail.
• The contrast of your colour pairs, computed at build time against the WCAG criteria and shown on the colours page, for each context.
• /tokens.css: the CSS variables of your design system, light and dark, ready to plug into your own projects.
• 2 languages out of the box: French at the root, English under /en, with reciprocal hreflang pairs between translations. A page without a translation emits none. The code accepts more languages.
• A single configuration file, theme.config.ts: site address, default language, site name, permalink patterns per page type and per language, publisher for structured data, token files, CSS variable prefix, foundations, contrast pairs, font and stylesheet of the examples.
• The search engine mechanics, produced by a single route table: canonical URLs without a trailing slash, hreflang pairs, a sitemap that leaves out noindex pages, robots.txt and JSON-LD structured data (WebSite, WebPage, CollectionPage, TechArticle, FAQPage, BreadcrumbList).
• Redirects in a single file, redirects.json, written to dist/_redirects, with a fallback page for each redirected address.
• Command-line checks: npm run check:tokens reads your DTCG files without building the site (aliases, cycles, types, contrast, tokens cited by components); npm run check:seo checks canonicals, hreflang pairs, sitemap, JSON-LD, internal links and redirects; npm run check:coverage lists the old URLs that the new site would neither serve nor redirect.
• Guides in French and English: plugging in your tokens (docs/tokens.en.md, docs/tokens.fr.md) and leaving a hosted documentation service (docs/migration.en.md, docs/migration.fr.md).
• A made-up demo design system, Lisière, in both languages: 168 tokens (137 primitives and 31 semantic roles), 181 CSS variables, 17 contrast pairs, 8 components, 6 foundations and 4 guides, including “Contributing”. The built demo has 44 HTML pages, including 40 indexable pages in 20 translation pairs, and its redirects.json holds 3 example redirects. Replace all the content with your own.
• Version 1.0.0, with its changelog, and 148 files in total.

Theme files:

• At the root: README.md, README.en.md, CHANGELOG.md, package.json, package-lock.json, .nvmrc, theme.config.ts, astro.config.mjs, tsconfig.json and redirects.json.
• tokens/: the demo DTCG files, to replace with yours.
• src/content/: components, foundations, guides, pages and token descriptions, one folder per language.
• src/examples/: the HTML examples of the components.
• src/components/, src/layouts/, src/lib/ (including the DTCG reader), src/pages/ and src/styles/: the theme code.
• public/: the stylesheet of the examples.
• integrations/: writing _redirects and _headers, and loading the examples font.
• scripts/: the command-line checks.
• docs/: token-plugging and migration guides in French and English, sample export.

The licence text, LICENCE.txt, is at the root of the downloaded archive.

Production and AI

The theme code (Astro templates, DTCG reader, CSS, check scripts), the demo design system and the guides were produced with an AI assistant, then reviewed and checked before going on sale: build on two Node versions, type check, SEO checks, accessibility in light and dark modes, contrast recomputed independently and no horizontal scrolling. No image was generated by AI.

• Requirement: Node 22.23.4 or later, the minimum version for Astro 7. The .nvmrc file gives the theme’s development version (24).
• Astro 7, fully static output, with no client-side JavaScript (0 KB): the only <script> tags carry JSON-LD data.
• DTCG 2025.10 for the tokens: resolver file or a single token file, sets, modifiers and aliases, read by a dependency-free reader. An orphan alias, a cycle or an unknown type makes the build and check:tokens fail, naming the file and the token.
• Markdown for the content, with a strict frontmatter: an unknown field makes the build fail, naming the file.
• TypeScript for the configuration and the theme code.
• CSS without a framework: the theme’s look rests on its own set of tokens (prefix --dsd-), kept apart from your design system’s tokens. Light and dark modes follow the visitor’s system setting.
• Fonts: Bricolage Grotesque and Martian Mono for the theme, Geist for the demo examples (to replace with your design system’s font), under the SIL Open Font License 1.1, referenced through npm. No font file in the archive, no request to an external font service.
• Hosting: any static host that serves composants/bouton.html at /composants/bouton. If it reads _redirects and _headers, it applies them; otherwise the fallback page written for each redirected address is not a 301 redirect: before a migration, copy each line of redirects.json into your host’s redirect rules. Astro’s Node adapter is not supported in version 1.0.0.

Good to know before buying:

• The theme reads DTCG 2025.10 files: it does not convert other token formats.
• It does not import existing documentation: the migration guide covers the inventory of old URLs, the export, field mapping and the coverage check, but you move the content yourself.
• After a change in tokens/, restart npm run dev: the development server does not reload token files.
• Not included: search, code copy button, light/dark toggle, several versions of the design system in parallel, Figma sync, rendering of framework components (React, Vue), RSS feed (release notes included), automatic content importer, $extends of DTCG groups, wildcard redirects.

The theme is sold with the commercial licence: you may use and modify it to document your design system and your clients’ design systems, but you may not resell, share or redistribute its files, even modified, nor publish them as a reusable theme or template, public repository included. The fonts keep their own licence.

• To understand the format the theme reads: what the W3C DTCG standard really changes for design tokens.
• To see what documentation adds to a component library (in French): UI kit and design system, the differences.

1.0.0 (12 November 2026): first release.