Toilville design system

The canonical home for Toilville's brand assets, design tokens, and design-system code.

Where to find what you need

Looking for logos, icons, brand guidelines? → Brand/exports/

Looking for Affinity source files (.af, .afdesign) or brand design templates? → Brand/source/

Looking for design specs (color themes, patterns)? → Brand/specs/

Looking for design tokens (CSS variables) to build a product? → Brand/UDG/ + dist/

Looking for conceptual diagrams (wireframes, flowcharts)? → Concepts/

Looking for pitch decks or presentation templates? → Media/Decks/

---

Folder guide

Brand/ — all brand assets

Brand/exports/

Production-ready files ready to ship. If you're building a website or app, grab from here.

Brand/exports/
├── logos/          — Toilville, Rituals, SPELWork logos (PNG, SVG, vector formats)
├── icons/          — Icon sets (PNGs + SVGs)
└── guidelines/     — Brand guideline PDFs (how to use logos, color rules, etc.)

Brand/source/

Affinity design source files (.af, .afdesign, .afpub). This is where designers work. Don't hand-edit these in the repo — author locally, then export to Brand/exports/.

Brand/source/
├── design_system/  — Master brand guidelines, infographics, publishing templates
├── SPELWork/       — SPELWork brandguide, icon library, UI design files
├── Toilville/      — Toilville symbol library, stickers, org chart, podcast templates
└── SB53-law/       — Website design files

Brand/specs/

Written design specifications (markdown). Design decisions, color theme definitions, etc.

Brand/specs/
├── rituals/        — Rituals color theme specs (light/dark/old-school)
└── spelwork/       — SPELWork dashboard design specifications

Brand/UDG/

Design tokens in canonical form (DTCG JSON). For developers and the token generator.

• Brand/UDG/dtcg/color.json — baseline brand colors
• Brand/UDG/products/<product>/dtcg/color.json — product-specific color overrides
• Brand/UDG/README.md — detailed token authoring guide

---

Concepts/

SVG wireframes, conceptual diagrams, and thinking artifacts.

• SPELWork tensions matrix, forge overview, governance signals, actor roles, etc.

Use these to understand system architecture and workflows.

---

Media/Decks/

Pitch decks, presentations, and design-system templates.

• Investor pitch for Rituals
• SPELWork theme deck
• Design-system template refinement archive
• Product landing-page templates

---

dist/

Auto-generated. Never hand-edit.

Token output files (CSS + DTCG JSON) for each product. Built by running just build.

• dist/rituals/{skin.css, tokens.dtcg.json} — Rituals tokens + dark/old-school themes
• dist/toilville/{skin.css, tokens.dtcg.json} — Toilville baseline tokens

---

udg/, generators/, components/, templates/

The token pipeline and code layer.

• udg/ — non-color token tiers (type, space, radius, border, shadow, motion) + generator config
• generators/ — Python script that merges brand tokens → dist/
• components/ — brand-agnostic component library (reads CSS variables)
• templates/ — brand-agnostic page templates (reads CSS variables)

See the README.md files in each folder for details.

---

Quick tasks

I need to export logos/icons

1. Open the design file from Brand/source/
2. Export to Brand/exports/{logos,icons}/
3. Commit the export

I need to update a design spec

1. Edit the markdown file in Brand/specs/
2. Commit

I need the latest tokens in my app

1. Pull this repo
2. Copy the relevant dist/<product>/{skin.css, tokens.dtcg.json} to your app
3. Load the CSS and reference the variables

I'm authoring a new color theme

1. Create or edit Brand/UDG/products/<product>/dtcg/color.json
2. Run just build-one <product> to regenerate
3. Check that dist/<product>/ looks right, then commit

I'm setting up a new product

1. Create udg/products/<name>/meta.yml with product metadata
2. Author colors in Brand/UDG/products/<name>/dtcg/color.json (or inherit baseline)
3. Run just build-one <name>
4. Commit

---

For token developers: The design token pipeline

Architecture

Design decision: Tokens are authored once, generated one-directionally, and every product works by swapping one CSS file.

Brand/UDG/dtcg/color.json                  ← Baseline colors (canonical)
Brand/UDG/products/<p>/dtcg/color.json     ← Product color overrides + themes
udg/baseline/tokens/{space,type,…}.yml    ← Non-color design tokens (6 tiers)
udg/products/<p>/meta.yml                 ← Product metadata & inheritance
             ↓ python udg/generators/extract.py (just build)
dist/<p>/{skin.css, tokens.dtcg.json}     ← Generated output (never edit by hand)
             ↓ import in your app
components/ + templates/                   ← Brand-agnostic code that reads CSS vars

The contract: no hardcoded colors, sizes, or spacing in code. Everything reads from CSS custom properties defined in skin.css.

Token tiers

Seven first-class token tiers: color · type · space · radius · border · shadow · motion

• Color is authored in DTCG format (Brand/UDG/dtcg/), carrying every theme per token. light is default; dark uses @media (prefers-color-scheme: dark); other themes (e.g., oldschool) emit :root[data-theme="…"] blocks.
• Non-color tiers are flat key: value YAML files under udg/.
• A product overrides any subset and inherits the rest from baseline.

Variable naming

Two var grammars, by audience:

• css_var_style: short — friendly names (--primary, --bg-surface, --safety-block). Used by Toilville (baseline).
• css_var_style: canonical — DTCG-mapped names (--udg-color-primary, etc.). Used by Rituals and external consumers that key off canonical names.

Current products

• Toilville — baseline product, short variable names
• Rituals — app product, canonical variable names + three color themes (light/dark/old-school)

Common commands

# Regenerate everything
just build

# Regenerate one product
just build-one rituals

# Check that dist/ is in sync with sources (CI gate)
just check

# View a template with a skin
open templates/_template/preview.html?product=toilville

Adding a new product

1. Create udg/products/<name>/meta.yml:

   name: myproduct
   display_name: "My Product"
   version: 0.1.0
   css_var_style: short  # or 'canonical'
   color_inherits_baseline: true  # inherit brand colors, or false to author custom
   

2. If you need custom colors, author Brand/UDG/products/<name>/dtcg/color.json (or skip to inherit baseline).

3. Regenerate: just build-one myproduct

---

References

• Brand/UDG/README.md — detailed guide to color token authoring (DTCG spec)
• .forgejo/workflows/udg-dist-check.yml — CI pipeline that verifies dist/ stays in sync
• components/README.md, templates/README.md — API contracts for each layer
• justfile — all available build tasks
• .pre-commit-config.yaml — local pre-commit hooks (drift gate runs before commit)