Design System

Design system

This page is the starting point for fiscalclock's visual identity and design system: what it is, the principles behind it, every design page, and where the source files live.

Last reviewed: 1 Nov 2026

What this is and why it matters

A design system is the set of shared decisions (colours, type, spacing, the logo, how diagrams and pages are drawn) and the files that hold them, so that the README, the docs, the diagrams and the social cards all look like one project. fiscalclock's results end up in financial reports, so its identity has one job: to make the project's method, "shown, not claimed", visible, and otherwise to stay out of the way (research brief). You do not need design training to use it: each page states its rules in tables, and every design term is defined in the Design-Glossary.

Status

As of 1 Nov 2026:

• Decided: the brand direction "Interval", with the [ ) symbol, a deep teal accent and IBM Plex Sans and IBM Plex Mono (DD-013); the design tokens and their build (DD-016); the logo, icon, card and banner files (DD-021 to DD-025); the smallest lockup, underlined links, date style and no decorative illustration (DD-026 to DD-029).
• Not decided: the website and docs stack (DD-009), which the tokens assume none of; an icon set; the default language tab in the docs; and terms for using the logo outside the project.
• Proposed: no extra assets (slides, banners) beyond the brief for now (DD-014).

Principles

These come from the closing section of the research brief and the decision log.

1. Precision is the signature. The memorable parts of the identity come from the library's own subject (half-open bounds, periods that tile a year, the extra week), not from decoration.
2. Neutrals plus one accent. Greys carry the system; the teal accent marks one meaning at a time and passes its contrast check in both themes.
3. Type does the talking. Figures are tabular wherever numbers or dates are compared (DD-020).
4. Evidence is a design element. Conformance counts, verification commands and "Last reviewed" dates get a designed place near the top of a page, never only in a footer.
5. Dark mode is equal to light. Every colour pair and every asset is designed and checked in both themes (DD-005).
6. Draw to scale, and never let colour carry meaning alone. Diagram widths are proportional to days; the extra week is hatched and labelled as well as coloured.
7. One source of truth. Values live in the token files; brand files are generated from them by script, never redrawn by eye (DD-016, DD-023).
8. No generated-design defaults. No gradients, glows, shadows, three-card feature grids or unbacked superlatives (DD-019; trust research).

Pages

Page	What it covers
Design-System	This page: what the design system is, its principles, the page map and the source files.
Brand-Foundation	Purpose, audience, personality, positioning and the brand idea [start, end_exclusive).
Voice-and-Writing	How fiscalclock writes: docs, README, release notes and error messages, with do and don't examples.
Logo-Guidelines	The [ ) symbol, its variants, clear space, minimum sizes, colours, icons and misuse.
Colour-System	The palette, the colour roles for each theme and the contrast checks behind them.
Typography	IBM Plex Sans and IBM Plex Mono, the type scale and the rules for figures and dates.
Design-Tokens	The token files, how they are built into CSS and JSON, and how to change one.
Layout-and-Spacing	The spacing scale, page widths, gutters and breakpoints.
Iconography-and-Illustration	How icons and illustrations are used, and what is avoided.
Diagrams-and-Data-Visuals	How calendars are drawn: to scale, with marked bounds and a table of the same numbers.
Docs-Components	The building blocks of a docs page, such as code blocks, callouts and the verification block.
Accessibility	The WCAG 2.2 rules every colour pair, control and diagram must meet in both themes.
Asset-Inventory	Every brand file, its size, its use and how it is made.
Design-Glossary	Plain-language definitions of every design term used on these pages.
Design-Decisions	The design decision log, DD-001 onwards, mirrored from the repository.

Where the source files live

Everything below is in the repository; the wiki explains it but holds no source of its own except the PNG illustrations in images/design/.

Path	What it holds
design/DECISIONS.md	The decision log. It wins over any wiki page that disagrees.
design/research-brief.md	Seven research tracks condensed into constraints.
design/research/	The full research notes, with sources and what could not be verified.
design/explorations/	The three brand directions sketched in Phase 3 and their palette check.
design/tokens/	The design token files (DTCG format) and their README.
design/tokens/generated/	Generated tokens.css, tokens.light.json, tokens.dark.json and the contrast report. Never edited by hand.
design/scripts/build_tokens.py	Builds the tokens and runs every contrast check (standard library only).
design/scripts/build_brand_assets.py	Generates every logo, icon, card and banner, and the wiki illustrations; renders PNGs with Inkscape.
design/scripts/check_brand.py	Checks that brand files and design pages use only token colours and token names.
design/scripts/contrast.py	Computes WCAG contrast ratios.
assets/brand/	Every brand file: logo, icons, social cards and README banner.

How to change something

1. Change the token file or the script, never a generated file or an exported PNG (tokens README).
2. Rebuild: python -I design/scripts/build_tokens.py, then the brand files if a brand colour or the logo changed.
3. Run python -I design/scripts/check_brand.py --wiki <path to the wiki clone>.
4. Add a row to design/DECISIONS.md with the question, the options, the choice and the reason, and update the wiki pages that show the value.

Links

• Design-Decisions, the decision log
• Research brief
• Design tokens README
• Home and Glossary for the project as a whole