FacetUI
DeutschGet started

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.

Coming soon

React ≥ 18 as a peer · or no React at all, as <facet-*> elements

tasks/create/quick-addactive
SEALobservation — empty
  • Enter adds the task on top
    • unit: 2 tests
    • property: no test
    • integration: no test
    • e2e: 1 test
    tested
  • An empty line adds nothing
    • unit: 1 test
    • property: 1 test
    • integration: no test
    • e2e: no test
    tested
  • Undo restores the last task
    • unit: no test
    • property: no test
    • integration: no test
    • e2e: no test
    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

quick-add.undoUndo restores the last tasktested

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

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.

Reading the repository~/work/taskflow
  1. doneConnect
  2. doneConfiguration
  3. doneRead records
  4. nowCount files
  5. —Find anchors
  6. —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.

  1. 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
  2. 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
  3. 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

  4. 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
Open register
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-controls or aria-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.

EXAMPLEApp.tsx
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, typography
  • facet-ui/coreData layer, no React
  • facet-ui/core/fixturesDemo data to build against
  • facet-ui/elementsThe same components as <facet-*>
  • facet-ui/elements/standaloneOne bundle, React baked in
  • facet-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

Put a requirement on screen. Gap included.

version 0.1.0