FACET UI · THE COMPONENT LIBRARY OF FACET
Show the requirements. Show the gap.
48 (measured by ls src/components/ui | wc -l) components that display an acceptance criterion alongside its evidence. What a test claims reads as claimed. What is missing stays visibly missing. What nobody measured stays a dash, not a zero.
React ≥ 18 as a peer · or no React at all, as <facet-*> elements
- Enter adds the task on top
- unit: 2 tests
- property: no test
- integration: no test
- e2e: 1 test
- An empty line adds nothing
- unit: 1 test
- property: 1 test
- integration: no test
- e2e: no test
- Undo restores the last task
- unit: no test
- property: no test
- integration: no test
- e2e: no test
size 412 lines (source: the repo scan, not the record)coverage — unmeasuredexample
- <facet-text>Text
- <facet-stack>Stack
- <facet-hairline>Hairline
- <facet-surface>Surface
- <facet-mark>Mark
- <facet-dot>Dot
- <facet-bar>Bar
- <facet-segment-band>SegmentBand
- <facet-counter>Counter
- <facet-probe-number>ProbeNumber
- <facet-scan-value>ScanValue
- <facet-quiet-line>QuietLine
- <facet-kbd>Kbd
- <facet-skeleton>Skeleton
- <facet-button>Button
- <facet-stat-value>StatValue
- <facet-coverage-ring>CoverageRing
- <facet-field-row>FieldRow
- <facet-focus-row>FocusRow
- <facet-rest-cloud>RestCloud
- <facet-sheet>Sheet
- <facet-blind>Blind
- <facet-trail>Trail
- <facet-depth-ladder>DepthLadder
- <facet-empty-state>EmptyState
- <facet-error-state>ErrorState
- <facet-index-progress>IndexProgress
- <facet-gherkin-statement>GherkinStatement
- <facet-seal>Seal
- <facet-lifecycle-badge>LifecycleBadge
- <facet-proof-matrix>ProofMatrix
- <facet-anchor-map>AnchorMap
- <facet-scenario-ledger>ScenarioLedger
- <facet-test-pyramid>TestPyramid
- <facet-knowledge-slots>KnowledgeSlots
- <facet-clause-sheet>ClauseSheet
- <facet-field-sheet>FieldSheet
- <facet-evidence-ledger>EvidenceLedger
- <facet-signal-stack>SignalStack
- <facet-record-source>RecordSource
- <facet-record-picker>RecordPicker
- <facet-companion>Companion
- <facet-dependency-fan>DependencyFan
- <facet-entry-cards>EntryCards
- <facet-group-tiles>GroupTiles
- <facet-markdown>Markdown
- <facet-role-gate>RoleGate
- <facet-timeline>Timeline
THE CRITERION AND ITS EVIDENCE
One acceptance criterion. Four honest answers.
A scenario row in ScenarioLedger does not just say “done”. It shows whether a test entry refers to the acceptance criterion and whether an implementation anchor exists in the repository. Pick a state.
SCENARIOLEDGER · ONE ROW · PREVIEW
Given a list with one task just addedWhen I press undoThen the task is gone and the list is as before
- unit: 1 test
- property: no test
- integration: no test
- e2e: no test
REDEEMED BY— no implementation anchor for this criterion
Example row. Columns are the four test kinds the component knows: unit, property, integration, end-to-end.
WHAT THE ROW SAYS
“A test entry refers to it, but no implementation anchor exists.”
WHAT IT REFUSES TO DO
To hide the gap behind the green. A passing test that no code claims is still a gap, and it says so.
An empty cell stays empty. ProofMatrix draws a hairline frame where no test exists, not a 0.
COUNTED, WITH THE COMMAND THAT COUNTED IT
Every number here came from a command.
- components
- 48
- Counted by
ls src/components/ui | wc -l - custom elements
- 48
- Counted by
FACET_ELEMENT_TAGS, src/elements/index.ts - story exports
- 182
- Counted by
grep -c "^export const" *.stories.tsx, summed - test suites
- 68
- Counted by
pnpm test:coverage - tests
- 990
- Counted by
pnpm test:coverage - line coverage
- 97 %
- Counted by
pnpm test:coverage - coverage threshold, configured
- 90/80/90/90
- Counted by
jest.config.ts:22
SIX LAYERS · ONE FORM LANGUAGE
From a hairline to a proof matrix.
Six layers, one form language: paper instead of cards, hairlines instead of boxes, no rounding, no shadows. Every component is also a custom element under the same name.
48 (measured by ls src/components/ui | wc -l) components · 48 (measured by FACET_ELEMENT_TAGS, src/elements/index.ts) elements
FACET ORGANISMS
The vocabulary of evidence: seals, ledgers, matrices, anchors.
- GherkinStatement
<facet-gherkin-statement>Given / When / Then, set as type. - Seal
<facet-seal>Seven stripes, one per facet. It counts and does not grade. - LifecycleBadge
<facet-lifecycle-badge>active · planned · deprecated · draft, with age. - ProofMatrix
<facet-proof-matrix>Scenarios × test kinds. An empty cell stays empty. - AnchorMap
<facet-anchor-map> - ScenarioLedger
<facet-scenario-ledger>Each acceptance criterion, its linked tests and its implementation anchor. - TestPyramid
<facet-test-pyramid> - KnowledgeSlots
<facet-knowledge-slots> - ClauseSheet
<facet-clause-sheet> - FieldSheet
<facet-field-sheet> - EvidenceLedger
<facet-evidence-ledger> - SignalStack
<facet-signal-stack> - RecordSource
<facet-record-source> - RecordPicker
<facet-record-picker>Search records, acceptance criteria, tests and code paths.
PREVIEW · EXAMPLE
Seal
active · 34 days · LifecycleBadge
Given an open listWhen I type a task and press EnterThen it appears on top
GherkinStatement
INDEXPROGRESS
A loading bar that won’t guess.
While the host only counts, you see the count, and the bar stays empty. A percentage appears the moment the denominator is known. And every phase starts its numbers from zero, so a stale “1 204 of 2 481” does not sit under the wrong step.
- doneConnect
- doneConfiguration
- doneRead records
- nowCount files
- —Find anchors
- —Build model
1 204no percent without a denominator
files in the repo · counted so far. The bar waits for a total.
Example: a load in phases, with sample counts
FOUR RULES IN EVERY COMPONENT
Honesty is not a style. It’s the contract.
01
Every word comes from a field.
A text is a field value, an enum, a date, a path, an id, or a count of those. No field, no sentence. It gets struck, not invented.
- owner
- team-tasks
- pitfalls
- — not answered
02
Colour does not work alone.
Rank, weight, position or shape carry the meaning too. Red is reserved for one thing: a deadline that has passed. Take the colour away and read it again.
- Enter adds the task on top
- unit: 2 tests
- e2e: 1 test
- Undo restores the last task
- unit: no test
- e2e: no test
- An empty line adds nothing
- unit: 1 test
- e2e: no test
- Enter adds the task on top
03
Origin stays visible.
The record schema knows no line counts and no commits. So a value from the repo scan is underlined with dots. Hover or focus it to see where it came from.
touched in 6 commits (source: the repo scan, not the record)status active · from the record
04
Four states, all named.
Ready, loading, empty, error. Loading keeps the final geometry. Empty names the missing facet. Error names the file and the line.
Enter adds the task on top
An empty line adds nothing
2 tested
TOKENS
Each colour says exactly one thing.
Signal is the way on. Tested is green. Planned is ochre. Overdue is the only real warning. One stylesheet, facet-ui/tokens.css, carries them into any page.
A dark palette used by the Atlas interface.
- Paper
--facet-bg#111318 - Surface
--facet-surface#1b1d21 - Line
--facet-border#2c3038 - Ink
--facet-ink#f2f3f0 - Ink, quieter
--facet-ink-2#c9cbc6 - Signal · the way on
--facet-signal#8fabff - Tested
--ok#74c49e - Planned
--plan#e2b45c - Overdue
--frist#f08e73
THE SAME ROWS, RE-TOKENED · PREVIEW
tasks/create/quick-addactive
6/7
- Enter adds the task on toptested
- Undo restores the last taskplanned
- Review assumption by 2026-09-30overdue
- TYPE
- IBM Plex Sans and Plex Mono. Ten sizes, 9.5 to 34 px.
- from
tokens.css, --text-* - GRID
- Seven steps: 4 · 8 · 12 · 16 · 20 · 28 · 40.
- from
tokens.css, --space-* - MOTION
- 200 to 300 ms. Switched off under reduced motion.
- from
tokens.css, --motion-*
MOTION
Movement says where things come from.
A register rises from below. A detail slides in from the right. The mark opens once and comes to rest. It only keeps moving while something is not there yet.
MARK · OPEN, PLAYS ONCE
block 44 × 78 · gap 12 · offset 22 · field 100 × 100
MARK · LOAD, LOOPS WHILE WAITING
Five equal bars, the mark taken apart. It has no end state, so it stays a loop.
ORIGIN DIRECTION
- register · quick-add
- register · invite-link
- register · discount-codes
SEAL · SEVEN STRIPES, ONE PER FACET
The stripe does not grade. It counts.
intent · contract · verification · observation · knowledge · lineage · anchors
ACCESSIBILITY, CHECKED BY A LINTER
The first run found real bugs.
The accessibility lint went in because the requirement was there, and a requirement without a check is a statement of intent. On its first run it found two defects. Both are fixed.
FOUND
The search box was a combobox without
aria-controlsoraria-activedescendant. A screen reader did not announce the hit you were on.FOUND
The depth ladder listened for arrow keys on an element that could not take focus. The keys now live on the tabs, which can.
- 83
- aria- and role= sites in component code
grep -rn --include='*.tsx' "aria-\|role=" src/components | grep -v "spec\|stories" | wc -l- —
- manual screen-reader audit · not documented
DEPTHLADDER · A REAL TABLIST · PREVIEW
ANSWER
6 of 7 facets filled. Observation is empty.
- → one step deeper
- ← back
- Esc closes a Sheet or Blind, each owns its own
Example
THREE WAYS IN, ONE SOURCE TREE
React, no React, or no rendering at all.
import { Seal, ProofMatrix, GherkinStatement } from "facet-ui";import "facet-ui/tokens.css"; <Seal present={{ intent: true, contract: true }} /><ProofMatrix scenarios={record.scenarios} /><GherkinStatement statement={scenario.statement} />
Drop a record in. Get its evidence out.
Each component comes as a logic wrapper around a purely presentational part. Use the default, or take withSealLogic and draw your own.
facet-uiReact components, tokens, typographyfacet-ui/coreData layer, no Reactfacet-ui/core/fixturesDemo data to build againstfacet-ui/elementsThe same components as <facet-*>facet-ui/elements/standaloneOne bundle, React baked infacet-ui/tokens.cssThe tokens as one stylesheet
USED IN ATLAS
Atlas builds its model through this library.
Atlas, FACET’s reader in the browser, builds its model with facet-ui/core and takes its colours from facet-ui/tokens.css. Its own interface draws on top.
Atlas does not import the React components today. The numbers say exactly what it does import.
- Atlas files that import from facet-ui
- 71
- Counted by
grep -rl 'from "facet-ui' web/atlas/src | wc -l - imports of facet-ui/core
- 72
- Counted by
grep -rho 'from "facet-ui[^"]*"' web/atlas/src | sort | uniq -c - import of the demo data
- 1
- Counted by
grep -rho 'from "facet-ui[^"]*"' web/atlas/src | sort | uniq -c - stylesheet: facet-ui/tokens.css
- 1
- Counted by
web/atlas/src/app/globals.css:1