Docs Components

Docs Components

This page describes the building blocks of fiscalclock's future documentation site (code blocks, language tabs, callouts, tables, date display, API reference pages, evidence blocks and page chrome) in terms of design tokens, without assuming any docs framework.

Last reviewed: 1 Nov 2026

What this is and why it matters

A component is a reusable piece of a page, such as a code block or a warning box, that looks and behaves the same everywhere. Writing them down before a site exists means any docs framework can be themed to match, and readers see the same cues on every page: where code is, what is a warning, which numbers are dates. Every value is given as a token (a named design value such as color.code.bg, defined on Design-Tokens), so nothing here depends on a particular tool.

Status: every component on this page is Proposed. No docs site exists and its stack is not chosen (DD-009 in DECISIONS.md). The tokens themselves are built and their colour pairs are contrast-checked (contrast.md). Token names map to CSS variables by replacing dots with hyphens and adding --fc-, for example color.code.bg is --fc-color-code-bg; a composite type.* token becomes one variable per property, such as --fc-type-code-font-family (DD-017).

Terms used on this page

Term	Meaning here
callout (admonition)	A boxed paragraph that interrupts the text to warn or inform, labelled "Note", "Warning" and so on.
tabular figures	Digits that all have the same width, so numbers and dates line up in columns (font-variant-numeric: tabular-nums).
page chrome	Everything around the article: header, sidebar, footer, version label, edit link.
accessible name	The text a screen reader announces for a control.
llms.txt	A plain-text index of a site's pages for AI agents and other programs; five of eleven sampled docs sites expose one or a Markdown view (peer analysis).

Code blocks

Used for definitions, calls, JSON output and shell commands.

Part	Token or rule
Font	type.code: font.family.mono (IBM Plex Mono with fallbacks), font.size.sm (0.875rem), weight font.weight.regular, line height font.line-height.body (1.6)
Background	color.code.bg
Text	color.code.text
Syntax colours	color.code.keyword (keywords, imports), color.code.string (string literals, including dates), color.code.comment (comments). No other highlighting colours.
Border and corners	border-width.thin in color.border.default; radius.md
Padding	space.4 inside; space.5 between a block and the text around it
Header strip	Language label on the left in type.small and color.text.muted (Rust, Python, JavaScript, JSON, Shell); copy button on the right
Copy button	Visible text or icon with the accessible name "Copy code"; pointer target at least 24 × 24 CSS px (WCAG 2.5.8); after copying, the label changes to "Copied" and is announced through an aria-live="polite" region; focus ring color.focus.ring at border-width.thick
Long lines	Never wrap. Lines scroll sideways (white-space: pre; overflow-x: auto). The scrolling block is focusable (tabindex="0") so keyboard users can scroll it (WCAG 2.1.1 Keyboard).
Shell commands	No $ prompt in the copied text, so a pasted command runs as is

Why JSON is never wrapped: the core's JSON output has "no insignificant whitespace" (spec/api-v1.md), and the bindings return it byte for byte. A soft-wrapped line looks like two lines of output. When a page pretty-prints JSON for reading, it says so under the block ("Formatted for reading; the API returns one line") and the copy button copies the exact one-line output.

Contrast of every code colour on color.code.bg is checked: at least 5.64:1 in light and 7.04:1 in dark (contrast.md).

Language tabs

fiscalclock ships the same operations in Rust, Python and JavaScript with byte-identical JSON results (README). Tabs let a reader see only their language.

Rule	Detail	Source
Three tabs, in this order	Rust, Python, JavaScript (the order of the README's package table). A tab for the CLI is added when the CLI ships (planned for 0.4.0).	README
One choice switches the whole page	Choosing Python on one example switches every example on the page.	Claude Docs uses one page-level selector (peer analysis, pattern 6)
The choice is remembered	Stored in the browser (localStorage) and applied on every page and on return visits. A URL parameter such as ?lang=python overrides it, so a shared link shows the sender's language.	Design judgement
Default before any choice	Not decided (Proposed: not decided). DD-002 names no primary audience.	DECISIONS.md
Output shown once	Because the JSON is identical in every language, the output block sits below the tabs and does not change with them.	ADR-0019
Accessible tabs	role="tablist", role="tab" and role="tabpanel", arrow keys move between tabs.	WAI-ARIA tabs pattern
Works without scripts	All three blocks are shown one after another with a heading each.	Design judgement
Look	Tab labels in type.small; the selected tab has color.text.default and a border-width.thick underline in color.accent.default; the others color.text.muted. The underline is the non-colour cue for the selected tab.	WCAG 1.4.1

Callouts

Each callout has a visible word label as its first line, an optional icon beside the label, a border-width.thick left border, and a color.bg.subtle background. The label and border use the colour in the table; body text stays color.text.default. The word carries the meaning; the colour and icon repeat it (WCAG 1.4.1). No icon set is chosen yet, so until one is, callouts show the label only (Iconography-and-Illustration).

Kind	Label text	Colour token	Use for	Checked contrast on color.bg.subtle (light / dark)
Note	"Note"	color.status.info	Extra context that helps but can be skipped	6.53:1 / 8.07:1
Warning	"Warning"	color.status.warning	A choice that can give wrong dates if misread, such as year_number	5.43:1 / 9.38:1
Danger	"Danger"	color.status.danger	Something that loses data or breaks a build, such as a breaking change	5.78:1 / 7.62:1
Illustrative example	"Illustrative example"	color.text.muted for the label, color.border.strong for the border	Example definitions that are not built in, such as NRF 4-5-4	Label 6.67:1 / 7.04:1; border 3.68:1 / 3.55:1

Ratios from contrast.md. Callouts are not placed on color.bg.raised, where the status colours are not checked.

The "Illustrative example" callout exists because fiscalclock has no named calendars (ADR-0004) and AGENTS.md requires unverified or illustrative material to be marked wherever it appears (evidence rule 4). Example text, from the README:

Illustrative example This definition describes the NRF 4-5-4 retail calendar. It is an example, not a built-in: fiscalclock has no named calendars.

Markup (framework-neutral):

<aside class="callout callout--warning">
  <p class="callout__label"><svg aria-hidden="true" …></svg>Warning</p>
  <p>…</p>
</aside>

A success callout is not defined: the docs report checks through evidence blocks, not through green boxes.

Tables

Rule	Token or detail	Source
Tabular lining figures in every table	font-variant-numeric: tabular-nums lining-nums	DD-020; typography research
Dates as ISO YYYY-MM-DD	Set in the text face (type.body or type.small), not the code face	Typography research, rule 8
Numbers right-aligned; dates and labels left-aligned	ISO dates have a fixed width, so they line up either way	Design judgement
Period columns in API order	level, year, index, start, end_exclusive, last_day, days, weeks, has_extra_week	spec/api-v1.md
Always both start and end_exclusive	last_day may be added, headed "last_day (derived)"; never an inclusive end alone	Design rule 5 in AGENTS.md
Header row	type.small, font.weight.semibold, color.text.default on color.bg.subtle	Token descriptions
Row separators	border-width.thin in color.border.default	Token descriptions
Highlighted row	color.bg.accent-subtle plus a word in the row (for example "extra week"); never the tint alone	WCAG 1.4.1
Booleans and keys	As the API writes them: true, false, null in the code face	spec/api-v1.md
Narrow screens	The table scrolls sideways inside a focusable wrapper; columns are not dropped	Design judgement

Example (values from the oracle vector nrf-4-5-4.json; NRF 4-5-4 is an illustrative example):

level	year	index	start	end_exclusive	last_day (derived)	days	weeks	has_extra_week
quarter	2023	3	2023-07-30	2023-10-29	2023-10-28	91	13	false
quarter	2023	4	2023-10-29	2024-02-04	2024-02-03	98	14	true

Period and date display

Rule	Example	Source
A period is written [start, end_exclusive)	[2023-10-29, 2024-02-04)	spec/api-v1.md; ADR-0007
In prose, spell the brackets out the first time on a page	"from 2023-10-29 (included) to 2024-02-04 (excluded)"	Design judgement for non-programmers
last_day is shown as derived, never instead of end_exclusive	"last day 2024-02-03 (derived: end_exclusive minus one day)"	Design rule 5 in AGENTS.md
ISO dates first; a named-month form may follow for readers outside engineering	2024-02-03 (3 February 2024)	Trust research, section 6.6
No time of day, time zone or clock icon next to a date		Trust research, section 6.6
Week-based years carry their length	FY2023 (53 weeks)	Domain visuals, "Annual reports"
Dates in HTML use <time datetime="2023-10-29">		HTML Standard, time element
Tabular figures for every date	font-variant-numeric: tabular-nums lining-nums	DD-020

The bracket and parenthesis in [start, end_exclusive) are the same idea as the logo: a closed bracket for the included start and an open parenthesis for the excluded end (Logo-Guidelines).

API reference page layout

One page per operation in the operations table, in this order:

#	Section	Content
1	Title and summary	The operation name in the code face (period) and one sentence from the spec
2	Signature	One line per language under the language tabs, copied from the package source
3	Parameters	Table: name, type, required or optional, meaning, allowed range
4	Returns	The result shape, linked to its definition in spec/api-v1.md (Period, Location)
5	Errors	Table: code, path, when it happens; then one example error object showing code, path, message, hint and details. Codes link to the error catalogue.
6	Example	The same call in Rust, Python and JavaScript under tabs, then the JSON output once
7	Evidence	An evidence block linking the conformance vectors that test this operation
8	See also	Related operations and spec sections

Sketch for period (signatures from calendar.rs, the Python package and the npm package):

pub fn period(&self, level: Level, year: i32, index: Option<u32>) -> Result<Period, Error>
let q4 = cal.period(Level::Quarter, 2023, Some(4))?;

def period(self, level: Level, year: int, index: Optional[int] = None) -> Period
q4 = cal.period("quarter", 2023, 4)

period(level: Level, year: number, index?: number | null): Period
const q4 = cal.period("quarter", 2023, 4);

Output, identical in every language. This is the Period example in spec/api-v1.md, and the oracle vector nrf-4-5-4.json expects the same values for the README's illustrative NRF 4-5-4 definition:

{"level":"quarter","year":2023,"index":4,"start":"2023-10-29","end_exclusive":"2024-02-04","last_day":"2024-02-03","days":98,"weeks":14,"has_extra_week":true}

Errors table for period, from the spec's "Paths for common errors":

code	path	When
PERIOD_NOT_FOUND	index	No period has those coordinates
OUT_OF_RANGE	year	The fiscal year is outside the supported range
INVALID_ARGUMENT	index	An index is given for a year

Error objects are shown whole, as the spec defines them, for example:

{"code":"WEEKS_SUM_MISMATCH","path":"subdivision.periods","message":"periods sum to 51 weeks, expected 52","hint":"add one week to a period","details":null}

code and path are stable; the page says that message and hint wording may change (spec/api-v1.md). In the error table, code and path are set in the code face; the hint is plain text.

Evidence blocks

Also called the verification block. A small block at the end of each reference page and guide, set in type.small and color.text.muted on color.bg.subtle, that says how the page's claims are checked. It makes the evidence visible where people look (trust research, rules R1 and R9).

Field	Example	Rule
Since version	0.1.0	From the changelog
Last reviewed	1 Nov 2026	Set by the person who reviewed the page
Tested by	oracle/nrf-4-5-4.json, errors/runtime-nrf.json	Links to vector files, not a hand-typed count
Source of expected values	Independent oracle, or a cited source	From the vector's source field
Case count	Generated by CI from the test run, never typed	Trust research, section 7.1

Page chrome and trust signals

Signal	Where	Detail	Source
Version and status	Header or sidebar	The current version and its status, for example "0.1.0: format and API are v1 drafts and may change before 1.0", styled as plain text, not a badge	Trust research, section 7.4; README status
Changelog	Header and sidebar	A first-class page with the same typography	Trust research, section 7.4; CHANGELOG.md
Edit this page	End of article	Links to the source file on GitHub	Seen on DuckDB, Tokio and Deno (peer analysis)
Last updated	End of article	From the last commit to the page source, generated at build time	Seen on Vercel (peer analysis)
Last reviewed	Top of article	The date a person last checked the page, as on this wiki	Trust research, section 7.5
Markdown view and llms.txt	Header menu ("View as Markdown", "Copy page") and site root	For agents and for readers who want plain text	Peer analysis, pattern 7; DD-002 names AI agents as an audience
Licence	Footer	The SPDX expression MIT OR Apache-2.0	Trust research, section 7.4
Maintainer, governance and security policy	Footer	Named maintainer; link to SECURITY.md	Trust research, section 7.5
Verify this release	Release and install pages	The exact gh attestation verify command and what a pass looks like	Trust research, section 7.3; README supply chain
Badges	README and home page only	Only signals CI computes and could fail (CI status, conformance count); no informational badges	Trust research, section 7.1

Layout of the chrome (column widths, header height) is on Layout-and-Spacing.

Open questions

• Which language tab is shown before the reader chooses (Proposed: not decided).
• Whether the "Illustrative example" callout needs its own token instead of reusing color.text.muted and color.border.strong.
• The docs framework (DD-009); each component above must be checked once in that framework, in both themes and with forced colours.

Links

• Design-System, Design-Tokens, Colour-System, Typography, Layout-and-Spacing, Iconography-and-Illustration, Diagrams-and-Data-Visuals, Accessibility, Voice-and-Writing, Design-Decisions
• Specification: spec/api-v1.md, spec/definition-v1.md
• Research: peer-analysis.md, trust-and-credibility.md, typography.md
• Tokens: design/tokens/README.md, tokens.css