Repository navigation
Iconography and Illustration
This page sets the rules for pictures in fiscalclock's documentation: why it uses no decorative illustration, what imagery it uses instead, and what any future icon set must meet.
Last reviewed: 1 Nov 2026
An illustration is a picture that sets a mood rather than carrying information; an icon is a small symbol, such as a warning triangle, that stands for an idea. People use fiscalclock's results for financial reporting dates, so every picture in its documentation should be something a reader can check. That rules out decorative art and leaves two kinds of imagery: diagrams drawn from real calendar arithmetic, and the library's real input and output. Icons are allowed only as helpers beside words.
| Term | Meaning here |
|---|---|
| decorative illustration | A picture whose job is to look good: hero art, abstract shapes, stock drawings, generated images. |
| diagram | A drawing whose shapes stand for data, such as a fiscal year drawn to scale. Rules on Diagrams-and-Data-Visuals. |
| real output | A definition, a call and the JSON fiscalclock returns for it, shown as text. |
| icon set | A family of icons drawn to one set of rules (same canvas, same line width), usually published as SVG files. |
| stroke weight | The width of the lines an icon is drawn with. |
| grid (canvas) | The square an icon is drawn in, for example 24 × 24 units, which fixes its proportions and padding. |
| accessible name | The text a screen reader announces for an element, for example from aria-label or visible text. |
Decided in DD-029.
Status: decided as a design rule, following the trust research (trust-and-credibility.md, rules R4 and R11). Not yet recorded as a DD entry in DECISIONS.md; see Open questions.
| Use | Do not use |
|---|---|
| To-scale diagrams of an actual calendar definition, labelled with that definition and the source of its dates | Stock illustration, hero art, abstract shapes, 3D blobs |
| Real output: a JSON definition, the call, and the JSON it returns | AI-generated imagery |
| The logo, as set out on Logo-Guidelines | Purple-to-blue or mesh gradients, glows, glassmorphism |
Tables of dates with start, end_exclusive and last_day
|
A row of three icon cards with one-line benefit claims |
| A screenshot of a real tool when a page documents that tool (Proposed) | Clock faces or times of day next to a date result |
| Plain typography and spacing when no picture is needed | Customer-logo walls and product-screenshot heroes |
Why, with the evidence for each:
| Reason | Source |
|---|---|
| Pages that lead with generic visual tells (gradients, glows, three-card grids, stock or generated imagery) look like generated sites; the evidence is practitioner commentary only, so this is a judgement, not a measured effect. The same section says to lead with "an actual definition, the actual JSON it returns and a to-scale diagram of an actual calendar". | Trust research, section 8 |
| Polish must never outrun proof: anything illustrative or unverified is labelled in the design itself. | Trust research, rule R4 |
| Familiar page structures score well on first impressions; identity should come from typography, the mark, diagrams and real content. | Trust research, section 2.2 |
| A clock face or time of day beside a date result implies a timestamp, which the library rejects. |
Trust research, section 6.6; TIMESTAMP_REJECTED in spec/api-v1.md
|
| Glow behind a hero object, gradient-filled marks, customer-logo walls and screenshot heroes were seen on admired sites' marketing pages, never in their docs. | Peer analysis, "Clichés to avoid" |
| No sampled docs site draws a fiscal year to scale or marks a half-open boundary, so fiscalclock's own diagrams are a way to look distinct with content rather than decoration. | Domain visuals, "What this survey shows" |
| You want to | Use |
|---|---|
| Explain how a year divides into quarters, periods and weeks | A year strip (D1) or week grid (D2) on Diagrams-and-Data-Visuals |
Explain start, end_exclusive and last_day
|
A boundary detail (D3) |
| Show what the library does | A definition, the call and its JSON output, in a code block (Docs-Components) |
| Make a page feel less bare | Nothing. Good headings, spacing and one example do this job (Layout-and-Spacing). |
| Show a well-known calendar such as NRF 4-5-4 | A diagram labelled "Illustrative example", because fiscalclock has no built-in calendars (ADR-0004) |
Real output shown on a page should be copied from a conformance vector or a spec example, so that CI already checks it (Proposed). The project rule is that expected values never come from running fiscalclock (AGENTS.md); taking examples from vectors keeps docs on the same footing.
Status: Proposed: not decided. No icon set is chosen, and no page or asset uses icons yet.
- Callout labels (note, warning, danger, illustrative example), always beside the word (Docs-Components).
- Small controls on the future docs site: copy button, theme switch, external-link marker, menu.
- Never inside diagrams, which use outlines, hatching and text labels instead (Diagrams-and-Data-Visuals).
- Never as a replacement for the logo, and the logo symbol is not used as a UI icon (Proposed; logo rules are on Logo-Guidelines).
| # | Rule | How to check | Source |
|---|---|---|---|
| 1 |
Open licence that allows use, change and redistribution in an MIT OR Apache-2.0 project; its licence file is linked from this page with its SPDX identifier. |
Read the licence file in the set's repository. | Project licence in the README; DD-010 sets the same "open licences only" rule for fonts (DECISIONS.md). |
| 2 | One stroke weight. Every icon is drawn with the same line width at the same size; outline and filled styles are not mixed. | Open the SVGs: one stroke-width value, no filled variants. |
Design judgement, so icons read as one family. |
| 3 | One grid. Every icon uses the same square canvas and padding. | Every SVG has the same viewBox. |
Design judgement. |
| 4 |
Text label or accessible name. An icon beside visible text is hidden from screen readers (aria-hidden="true"). An icon-only control has an accessible name (aria-label) and a visible tooltip. An icon never stands alone as the only content. |
Inspect the accessibility tree in browser developer tools. | WCAG 2.2 1.1.1 Non-text Content and 4.1.2 Name, Role, Value. |
| 5 |
Colour from tokens. Icons use currentColor, so they take the colour of their text: color.text.default or color.text.muted, or the matching color.status.* token inside a callout. No other colours. |
Search the page CSS for colour values on icons. |
currentColor also follows forced-colour modes (accessibility research, section 6). Token values on Colour-System. |
| 6 | Never colour alone. The shape and the word carry the meaning; colour only repeats it. | View the page in greyscale. | WCAG 2.2 1.4.1 Use of Color. |
| 7 |
Contrast at least 3:1 for any icon that carries information. The allowed tokens already meet this: color.text.muted is at least 6.33:1 and every color.status.* at least 5.43:1 on the checked backgrounds. |
contrast.md |
WCAG 2.2 1.4.11 Non-text Contrast. |
| 8 | Pointer target at least 24 × 24 CSS px for an icon control, even when the icon is smaller. | Measure the clickable box in developer tools. | WCAG 2.2 2.5.8 Target Size (Minimum). |
| 9 |
Inline SVG, so currentColor and forced colours work (Proposed). |
No icon font in the page. | Accessibility research, section 6. |
| 10 |
Shown at font.size.md (1rem) next to body text and font.size.sm (0.875rem) next to small text (Proposed). |
Compare the icon's rendered size with the text beside it. | Design judgement; type sizes on Typography. |
Both candidates below meet rules 1 to 3 as published. Licences were read from each repository's licence file on 1 Nov 2026.
| Set | Licence (as of 1 Nov 2026) | Grid and stroke, as the set documents them | Note |
|---|---|---|---|
| Lucide | ISC; icons derived from Feather are under MIT. Both texts are in the licence file. | 24 × 24 canvas, 2 px strokes, round joins (icon specification) | The licence file lists which icons are under MIT, so a page using them must keep both notices. |
| Tabler Icons | MIT (licence file) | "designed on a 24x24 grid with a 2px stroke" (README) | The package also ships filled icons; rule 2 allows only one style, so use the outline icons only. |
At 16 px, a 2-unit stroke on a 24-unit grid renders 2 × 16 / 24 ≈ 1.33 px wide. Check that it stays visible next to IBM Plex Sans at that size before choosing.
How the choice is made: the owner picks a set (or none), and the choice is recorded as a new DD entry in DECISIONS.md and on Design-Decisions. Until then, callouts carry their text label alone, which satisfies rule 6 without an icon.
- Which icon set, if any (Proposed: not decided).
- Whether screenshots of real tools are allowed, and how they are kept current (Proposed).
fiscalclock is licensed under MIT OR Apache-2.0 (MIT, Apache-2.0). Last reviewed: 31 Oct 2026. Found an error on this page? Report it with the documentation form.