The components

Rules

• Closed by default. It is a way to leave, not a place to be.
• The panel pages. It never scrolls and never shrinks its tiles.
• Metrics come from the container width, so a phone frame on a desktop page still renders phone metrics.

Carried over

It is the only widget in the app that this product's design actually wants, and it was built and never wired up: zero call sites outside its own folder. The layout math in hc_nav_menu_layout.dart is genuinely good and re-deriving it would be wasted work.

Came across: resolveMetrics(), a direct port of resolveHcNavMenuMetrics, columns from the space available at full tile size; the panel PAGES rather than scrolling or shrinking, two metric sets chosen off the CONTAINER width, not the viewport, the collapsed bar's identity block, per-tile badges, selection, and the full keyboard model

Left behind: the app's theming — the deck drives it from role-colors.css instead, everything about how it is mounted in a Flutter tree, THE BELL. The widget places one in three of its four utility presets and gives it an unread badge; the deck took that default without anybody choosing it, and 34 frames shipped reading "2 unread" over an affordance that opens nothing. It opens nothing on purpose — mockup 22 states three times and mockup 20 once that there is NO INBOX ANYWHERE IN THIS PRODUCT. A reply is the other half of a send, and anything that needs a person waits in Now, which is a door on the same dock. Removed 2026-08-04: notifications is 'off' in every preset in _ds/xnav.js, the dead count attributes are gone from the deck, and the persistent utility is now the avatar alone. The button itself is still built, so a page could opt in with data-xnav-notifications; nothing does. When HcNavMenu is wired up in Flutter its preset needs the same change — porting the bell back is not a fix.

Why it is a component

The dock's two levels exist because a phone has no room. A rail has 860 points of it, so the binder stops being a level to descend into and becomes six rows under a label. It is a sibling of the dock rather than a mode on it: the app owns the door list and both render it, and none of the dock's hard parts — open state, paging, drag, the grid — apply to a column.

Rules

• Every door is shown. The rail does not page, does not scroll and has no second level.
• The group boundary is an index. The builder's level two starts somewhere else, and a rule that named the first binder key would draw no label at all there.
• NOT COLLAPSIBLE. The river is capped at 720 either way, so collapsing buys margin rather than content — and costs a second nav state on the surface whose job is answering 'where am I' without being asked.
• A label never wraps. The rail is 232 because the longest string, 'Record something', measures 129 at DM Sans 14/500.
• The marker is a dot and never a count. Ruling 4, and the same rule the dock follows.

Not for

• Below 1024. The dock is the navigation there and nothing about it changes.
• A collapsed or icon-only state. There is one rail, and it is this one.

Why it is a component

The library audit measured 155 solid CTAs and not one of them said what committing does — you read the button, you press it, and the screen tells you afterward. A commit control that cannot be drawn without its consequence is the only version of that rule a component can hold.

Rules

• The consequence is required. A bar with an action and no sentence is the thing this component exists to stop.
• One action. The bar is where the screen's single commit lives, so a river underneath it must not carry a second solid cta.
• At 1024 and above only. Below that the dock holds the bottom edge and ruling 3 settles the collision in the dock's favor; the screen keeps its cta in the river there.
• The consequence is trimmed at two lines. The bar is a fixed 76, and a consequence needing three lines is one the screen should be saying instead.

Not for

• A toolbar. It holds one action, not a row of them.
• A phone. See ruling 3.

Why it is a component

319 frames rest on it and it has never had a rule. It is also where two questions get settled that nothing else answers: whether a screen has an app bar and whether the dock's room is reserved (164 do, and exactly the 164 that have a dock).

Anatomy

Rules

• The notch is on every phone and is always the first child. It is the device rather than the product, and nothing is allowed to sit above it.
• A SCROLL WITH .nav-reserve AND A .navdock ARE THE SAME DECISION. 187 phones have both and 274 have neither; there is not one of either alone. The reserve exists to leave the dock its room, so adding a dock without it puts the last card under the dock.
• The app bar is optional and its absence is a choice rather than an omission: 46 phones carry a scroll and no app bar.
• A full-frame state REPLACES the screen, it does not cover it. The three block phones and the two cold phones contain the notch and that state and nothing else — no app bar, no scroll, no scrim. A state that needs the screen behind it is a scrim over a scroll, which is a different thing.
• At most one scroll. A phone is one screen.

Not for

• A desktop or tablet frame. Those lay out in .pic, .rail and .pane inside a .frame-wrap, with no phone around them.

Why it is a component

Its two slots were never written down. The leading slot is exclusive — no app bar carries both a mark and step dots — and the trailing slot is countable, which is the sort of thing a component either states or re-decides per page. It also went years without naming the back chevron, and because this file listed only the mark and the step dots, the Flutter app was built with no back button at all until a reader audited the frames.

Anatomy

Rules

• NEVER A TITLE. The screen's title is in the scroll, inside a screen_head, and an app bar that grows one gives the screen two titles at two sizes.
• The leading slot holds the mark OR the step dots, never both.
• Back is a chevron in an .icon-btn, and what decides its side is whether the leading slot is already taken, not depth and not the mark alone. A free leading slot may hold back; the pair never share it.
• At most two icon buttons, wrapped or not. A third is a menu, and the menu is the dock. Count them as descendants rather than children because .btn-area puts them one level down.
• Both slots are optional: an app bar may carry only a mark or only a button.

Not for

• Navigation. The dock is the navigation; the app bar is where the mark and at most two utilities live.

Why it is a component

It is the only thing on a phone that scrolls, and it owns the block rhythm — 243 of the deck's inline margins are gaps between its direct children. Its variants were being written by hand on 175 frames with no statement of what they mean.

Variants

• .nav-reserve leaves the dock its room. Present on exactly the 187 phones that have a .navdock and on no others.
• .lnkpage an account-less link surface. 22 instances; no dock, because there is nowhere else to go.
• .thread a conversation. One instance, and it is the only scroll that reads bottom-up.

Rules

• The screen scrolls; the app bar and the dock do not. That is what makes them chrome.
• Its direct children are blocks and the gap between two of them is --sp-block. Anything needing a tighter gap than that is one component with a wrapper, not two blocks.
• One screen_head, at the top, and only there.
• .nav-reserve is not decoration and not optional-by-taste — it pairs with the dock exactly. See phone.

Why it is a component

The deck had EIGHT hand-rolled overlays under four names on two pages — ob-sheet four times, ob-modal once and ob-side-scrim twice on 04, intake-sheet once on 25 — with three different scrims, two grounds, --r-lg against 24px, no height cap on any of them and not one close control between them: the way out was drawn nowhere except as the dimming. SIX ARE THIS NOW: the four phone sheets and the centered ob-modal on 04, and the correction sheet on 25. The ob-modal was the deck's one dialog, and a dialog is a sheet that forgot which edge it came from. The two ob-side-scrim panels are already side-anchored with a scrim and a way out, so what they need is the deck's desktop frames to become desk containers rather than a rule fix.

Anatomy

Rules

• One overlay, and this is it. Pick by what the reader can afford to lose: they can afford to lose their place, it is a screen; they cannot afford to pause at all, it is a say, which sits above the content and never over it; they need to come straight back to what is behind, it is this.
• It replaces no rung of the surface ladder. It sits above the ladder, temporarily, and the ladder resumes inside it.
• It caps its own height at 88%. A sheet that can reach the top edge is a screen wearing a scrim, and the sliver of the surface behind it is what says the reader has not gone anywhere.
• The scrim is clickable and is not a tab stop. The close control and Escape are the keyboard's routes out, and the way out is drawn — the four sheets converted from ob-sheet had a grab handle and no close control at all.
• The scrim darkens in both themes. Sheet.jsx mixes 32% of --on-surface, which is #F7F7F8 in dark and lights the receding page instead of dimming it; the deck's measured value is used and the package defect is Q192.
• Never nested, and it carries no navigation. A sheet opened from a sheet is a flow that should have been a screen.
• There is no dropdown and no dialog in this system. A dropdown hides the options it is choosing between, and this product's argument is that options get compared side by side. A dialog is a sheet that forgot which edge it came from.
• It has an accessible name, and the behavior comes with the claim. aria-modal is a claim about the whole page: focus moves in on open, Tab is contained, Escape closes, focus returns to whatever opened it, and the title names the dialog. A claim the keyboard does not keep is worse than no claim.
• overlay is the class, and page 04 meant something else by it: three desktop frames carried class="ob-desktop overlay" from before this component existed. They rendered correctly only because two classes out-specify one and the page's own block loads after components.css — an accident rather than a design. Renamed to ob-overlaid 2026-09-06.

Why it is a component

The surface ladder's middle rung, and it existed nowhere: zero selectors, zero instances, and --r-zone:0px declared and read by nothing, while --surface-container carried the comment 'a zone: a region of the screen, edge to edge' since the palette was written. Which left sixty bare options grouped by five different containers — eighteen in .opts on 07, sixteen straight in a .scroll, seventeen in an unclassed div across six pages, six inside a card or a field. One rung, re-decided five times.

Anatomy

Variants

• .region-left the heading reads from the left. The contents are left-aligned either way.

Rules

• Full width, square and flat. Those three are what tell a region from a card at a glance: a card is inset, rounded and raised. Give a region a radius and it becomes a very large card, which is the mistake it exists to prevent.
• A card says 'here is an object you can act on or cite', so wrapping a question and its answers in one claims the question is an object. A region claims nothing; it says only that everything inside belongs together.
• Ground to region to card is the deepest legal nesting. A region inside a region is not.
• The title is a block title — --text-lg at 700, the same step as a card head — and it names the region and nothing else. Bold at 21px carries more ink than the screen title's regular 27px, so a supporting fact parked there outranks the question the screen exists to ask.
• The eyebrow alone is a complete region. What is not allowed is neither eyebrow nor title, which is a gray band with no explanation.
• It runs to the screen edge, by canceling the scroll's gutter and putting it back inside.
• The package calls this Zone. It is region on both sides because hc_domain already exports a Zone — a room or area of the house — and the package's own first words for it are 'a region of the screen'. Ruled 2026-09-06.

Why it is a component

Ported from the reviewed design-system JSX, props and prompt; decision controls is the first product consumer.

Rules

• Empty selection shows an instruction without an inactive action.
• The action names its scope, with clear alongside.
• The caller docks it without covering content.

Why it is a component

It is on 134 frames and has never been a component. It exists today as three loose siblings with hand-typed gaps, and its two internal gaps are drawn at nine different values across the deck — eyebrow-to-title at 5, 6 and 7px; title-to-supporting-line at 5, 6, 8, 9, 10 and 16px. That is one component being re-decided 119 times.

Anatomy

Rules

• The eyebrow is where you are, never what this is. Kitchen · counter material is an eyebrow; Add an option is a title.
• The supporting line is one sentence. If it needs two, the second one belongs in a callout or is not needed.
• The whole header is one block. The gap below it comes from the container, not from the header.
• It never carries an action. A header that needs a button is a header plus a block.
• It is a direct child of the scroll. A .screen-head nested inside a card is a card head wearing the wrong component, and the gate refuses it.

Not for

• A section inside a screen — that is section_header.
• A card's own title. Three of these were wrongly wrapped during the extraction and put back; see card_head below.

Anatomy

Rules

• THE AIR ABOVE IT IS THE DIVIDER, so the header is CENTERED AND UNRULED. A named run is separated by --section-gap, and once that gap is there the rule is redundant decoration.
• left restores the ruled version, and it is for ONE case: a run whose trailing chip counts the rows beneath it. A trailing that is an action rather than a count stays centered beside the label.
• flush drops the lead-in for the first header on a screen, where the head above has already provided the air.
• A trailing chip describes the SECTION, never the first row in it.

Anatomy

Rules

• Not screen_head, and the difference is not size. A screen header names the screen and there is one; a card head names a card and there can be several on a screen. One component for both makes "one per screen" unenforceable for either.
• It uses .card-title. A .screen-title carrying its own font-size is this component wearing a style attribute, and the conformance gate now refuses it.

Variants

• .default white. Takes a hairline inset ring — a white card needs the edge.
• .card-quiet a lighter lift for a card inside a busy run. It sets no background and keeps the ring, so it is a card wearing a quieter shadow. This note read "quoting something somebody else said" until 2026-09-06, which described what the deck used it FOR rather than what it is; six of its instances are quotations and they keep it, because a quotation is a thing you cite.
• .card-absent flat and quiet, for a thing the app cannot do. IT IS NOT THE PACKAGE'S absent TONE, and that divergence is open: the package draws absent as the outline rung — transparent with an --outline-strong ring — and the deck fills it with --surface-container at the card radius, which is the region's ground wearing a card's shape. Under either reading a sentence does not belong on it: the outline rung is not for a sentence, and a region is a region of the screen rather than a thing on it. 18 of these held one paragraph and nothing else until 2026-09-06.

Rules

• A card takes a hairline, and there is no other kind of card. card-sage, card-clay and card-lav were removed on 2026-09-05 with the six tokens behind them: the design system has no tinted grounds, and what a tint used to say is now a word.
• The hairline is an inset ring, never a border — a real border moves the content in by a pixel and reflows every card.
• A card never sets its own top margin.
• A card takes the page's own ink. It does not recolor its text to match its ground.
• IT IS A CLAIM, NOT A CONTAINER. A question and its answers belong in a region, a lone figure belongs on the ground, and a set that is not an object belongs in an outlined block. Prose belongs on the ground in every case — the ladder's own words are "if you cannot name why a thing needs a surface, it belongs here", and the outline rung refuses a sentence outright because a boxed aside reads as an option nobody picked. A door is not prose: if the way in is drawn as a colored paragraph rather than as an affordance, draw the affordance rather than removing the card.
• One surface change per level, two levels deep at most: ground → card → rows, or ground → region → card. A card wrapping something that is itself structure — a spine, a region — is that structure's container and not a claim about it; four of them were removed on 2026-09-06 and one of those was the deck's only nesting violation.

Why it is a component

Twenty-four instances drawn at SIX gaps — 10, 12, 14, 16, 18 and 20px — for one relationship.

Rules

• It is a SIBLING that belongs to the card, not a slot. It sits on the page ground, outside the card padding, so it cannot be inside; but it hugs the thing it is about, so it is not an independent block either. That is why it is an adjacent-sibling rule rather than a wrapper.
• It takes --sp-snug. Give it the block rhythm and it stops reading as a footnote and starts reading as the next paragraph.
• This is what the block rhythm was waiting for: a container gap on .scroll would have given all 24 of these 22px.

Why it is a component

IT WAS FILED AS A ROW AND IT IS A SURFACE. This library's own kinds settle it — a row is 'a repeating line inside a surface', a surface 'holds other things, has a ground and a padding'. .opt has its own card ground, 24px of padding, an inset ring and a shadow, and 60 of its 60 instances are not inside a card at all — not one is, and the "30 of 35" this line hedged with was stale in both figures. It is the thing being chosen, drawn as its own object, and Q229 reads --r-card off that.

Anatomy

Variants

• .sel chosen. Takes the accent fill and the selected ring. 14 uses. It was 13 and one page wrote on for it, which matches no rule and drew that option unchosen (21-jobs.html); Q229.

Rules

• SELECTED IS A FILL, NOT A BORDER. The chosen option takes the accent as its ground so that a glance across a list finds it without reading.
• The annotation is not quietened when selected, and that is measured rather than preferred: on dark the selected fill carries its ink at 4.97:1, so a 90% mix toward the fill lands at 4.31 and fails. There is no quiet step available, so hierarchy is carried by weight and size instead.
• One line of annotation. An option needing a paragraph is a decision, and a decision gets a screen.

Not for

• A row in a list of things you are reading rather than choosing. That is row.
• A run of answers INSIDE a card. A raised, filled block within a card is a second card and the ladder does not stack, so selection there is the marker: that is pick_row.

Anatomy

Rules

• Rows inside a card are separated by nothing. No dividers between rows.
• The marker is vertically centered on the row, always, however many lines the name runs to.
• A row has at most one trailing slot. A chip AND a figure is two ideas fighting.
• The caption is where provenance goes — Their quote, 2 June, From QuickBooks, read this morning.

Why it is a component

It looks like a near-duplicate of row and it is not. THE CAPTION IS THE WHOLE DISTINCTION: ordinary rows may carry .c; inset rows never do. That is why an irow needs no .tx — the wrapper exists to group a name with its caption so the trailing slot can be pushed right, and with no caption there is nothing to group, so flex: 1 sits on .n itself.

Anatomy

Rules

• No caption. A line that needs a second line is a row, and the wrapper comes with it.
• The trailing slot is not optional here. An irow with nothing on the right is a name in a box, and it should be a row or a plain line.
• Rows of either kind are separated by the hairline --rule-ink and by nothing else.

Not for

• Anything with two lines of text. That is row.

Why it is a component

It is the only row in the deck built around a picture rather than a name, and the thumbnail is what makes it one component rather than a row with an image in the marker slot: a 56px square is not a 32px .ic and does not line up with one.

Anatomy

Rules

• No price and no call to action. A keep is something noticed, not something being decided; the moment it carries a figure it is an option and belongs in an intake.
• The room is a chip on the keep, and no room is a real and expected state rather than an error. Ten of these exist and the unfiled one is the interesting case.
• The thumbnail is always drawn, even when there is no image. A row of keeps with ragged left edges reads as broken.

Not for

• A document. That is a row with a count on the right, or the viewer.

Why it is a component

WHICH SHAPE IS A QUESTION ABOUT THE SURFACE. On the ground a choice is opt and selected is a fill; inside a card a fill cannot carry it, because a raised filled block within a card is a second card and the ladder does not stack. So the marker carries selection here — one surface, --rule-ink between rows, plain ink at every state. The class was in the vocabulary with no rule behind it until 2026-09-05: all thirteen rows inherited .mark from icons.css and nothing else, so the marker stacked above the name it marks.

Anatomy

Variants

• .on chosen. Ticks the marker and takes the name to 600. 4 uses.

Rules

• THE MARKER CARRIES SELECTION, and it is the only thing that changes. Weight, not hue, marks the chosen name.
• The name never turns blue. Blue text is a link everywhere else in the product, so a blue chosen option reads as somewhere to navigate.
• The rule sits BETWEEN rows — every row but the first — so a run does not open with a hairline under the card's own head.
• Only real answers belong in the list. Leaving the question is an escape, and escapes sit under the primary action as a text action.

Not for

• A choice standing on the ground, in a zone or bare. That is opt, and selected is a fill.
• A row in a list of things you are reading rather than choosing. That is row.

Why it is a component

A row's trailing slot is --text-xs in the variant ink — a QUALIFIER on the name, "Their quote, 2 June" — so putting an amount there demotes the one thing the reader came for. Here the answer sits at the name's own step, tabular, on one right edge, so a column of them compares vertically without the eye re-measuring each line. The rule is guidelines/data-hierarchy: every data card exists to answer one question, and a card that draws its inputs and its answer at the same weight makes the reader do the arithmetic the product was built to do for them.

Anatomy

Variants

• .clash the answer's ink when the row is over. On the value only, and on ONE row.

Rules

• THE ANSWER OWNS THE RIGHT EDGE, at the name's own step. A figure in a row's trailing slot is a qualifier; a figure here is the finding.
• WHAT THE ANSWER IS "OF" GOES UNDER THE ANSWER, not into the name's caption. "$22,000 set aside" beside "Primary bath" is a second fact about the room; "left of $22,000" under "$6,800" is that number doing its job.
• One caption or the other, never both. Two captions on one line is the reader choosing which to read.
• CLASH INK MARKS THE SINGLE ROW THAT IS OVER. Color on every row is five alarms, and a reader who sees five stops reading any of them.
• Nothing repeats down the column. An identical glyph on every row carries no information and spends the width the amount needs.

Not for

• A line you read or open, where the trailing thing is a note about the name rather than the answer. That is row.
• ONE headline figure on a card. That is kv, at the display step.
• A run of settled key-and-values that are not answers to one question. That is fact.

Why it is a component

Ported from the reviewed design-system JSX, props and prompt; decision controls is the first product consumer.

Rules

• Selection stays on the neutral card rung; a marker and primary ring carry it.
• Partial is a distinct mixed state.
• Read-only removes the selection control and preserves disclosure.
• Members indent to the name; the caller supplies ownership and counts.

Anatomy

Rules

• Numerals are tabular. A column of figures that does not align is a column that cannot be read.
• IT STACKS, AND IT NEVER PUTS A SENTENCE IN A COLUMN. Q225, ruled on this deck’s own content: 53 of the 144 values run past 25 characters and the longest is 119, while the longest key is 23 and the median is 9. A fixed key column is right for a Fact whose value is a figure and wrong for the third of them that are prose.
• THE VALUE TAKES THE STEP ABOVE THE LABEL — the value at the lead step, the label at the one caption treatment the other four captions take.
• THE HAIRLINE MARKS A SETTLED RUN, so the first item does not take one, and the block padding is symmetric because a Fact cannot see that it is last.

Why it is a component

It is the other key-and-value in this library and it is drawn for the opposite job to fact. A fact holds a fixed label column so a RUN of them reads as a column; a kv pins both ends to the card's edges so ONE of them reads as a headline. hc.css says so in its own comment beside .fact: right-aligned values fight the edge as soon as either side is long, which is why a run is never drawn this way.

Anatomy

Variants

• .clash the figure's ink when the answer is over. On the value only.

Rules

• ONE OR TWO ON A SURFACE, NEVER A RUN. A run of key-and-values is a fact list. The two components look alike and are not interchangeable.
• NO HAIRLINE BETWEEN THEM. fact carries .fact + .fact { border-top } and this deliberately does not, because it is not a settled run.
• Numerals are tabular. 10-now.html puts t-num on the value.
• THE KEY TAKES THE RAMP AS hc.css WRITES IT. tints.css used to escalate .kv .k to full ink on sage, lavender and clay, because the quiet ink measured 4.30:1 on light clay and failed AA. That sheet went with the tinted grounds on 2026-09-05; a card is white, where --on-surface-dense measures 8.38:1, so there is nothing left to escalate.

Why it is a component

It is the deck's whole argument about deadlines made visible. A due date on its own is a source of anxiety a person can do nothing with; the same date beside $0 and $1,200 is a choice with a price on it. The free side is drawn first, always, so the reader meets the outcome that is still available before the one that is not.

Anatomy

Rules

• BOTH FIGURES OR NEITHER. The pair is a comparison; one side alone is a bill.
• THE WORKING IS NOT OPTIONAL. 10-now.html states it directly: the slip is never shown without its cause. A number a person cannot interrogate is anxiety with a dollar sign on it, which is the thing this product exists to replace.
• THE FREE SIDE IS DRAWN FIRST. Reading order is the argument: the outcome still available, then the one that is not.
• Numerals are tabular, like every figure in this library.
• IT NEEDS NO CARD AND NO RULE. It is a figure, not a record: two numbers and the working behind them are one thought, and a container divides it. Bare on whatever it sits on.
• BARE MEANS IT CARRIES ITS OWN HEADING. With the card gone, naming the block and bounding it both fall to the block — and two large figures with no title are a number the reader has to reverse-engineer from its labels.
• THE VALUE CARRIES THE COLOR, NOT THE LABEL. The label is the family's one caption treatment; colors-status lists a figure's VALUE among the five places a color belongs, and a caption naming a figure is not one of them.
• ITS SPACING IS THE SHEET'S, NOT THE CALL SITE'S. 20px above the figures — the package's own figure, and the same gap whether what sits above is the head or a lead line inside a composite block — and the head's margin-bottom owns it where there is a head. Every one of the eleven instances typed its own margin-top until 2026-09-06: 16px once, 18px twice, 20px four times, --sp-block three times and nothing once, so on three pages the block sat flush against what was above it while its own figures sat 48px away.

Why it is a component

It is the deck's answer to a number with no provenance: every figure in it carries where it came from, and the source line is not optional. From QuickBooks, read this morning is the component.

Anatomy

Rules

• THE SOURCE IS NOT OPTIONAL. A figure with no provenance is the thing this product exists to replace.
• Two figures. Not one, which is a fact, and not four, which is a table.

Why it is a component

Named .loanbar and scoped to the construction loan alone until 2026-08-10, deliberately, so the next thing tempted to wear a progress bar had to argue for it rather than reach for it. 10-now's contingency card made that argument: contingency is a fixed pool the same way a loan is, just self-set rather than bank-set, and generalizing the existing shape (rename, neutral tone names) was the honest move against building a second one that looked the same and drifted. Page 21's GMP cap and page 33's cost-plus target still carry no bar — a fixed pool is the test, and neither of those is one.

Anatomy

Rules

• ONLY A FIXED POOL, SET ONCE. The total must not move because of anything that happens against it — a loan (the bank sets it and stops) and a contingency reserve (set aside once, spending against it doesn't grow it) qualify. A contract sum does not: a change order moves the total itself, which makes a fill against it answer how far through am I instead of what is the rest of it doing.
• THE SEGMENTS SUM TO THE WHOLE AND THE TRACK NEVER SHOWS. This is the test for whether anything could wear it: a fixed pool is fully allocated the day it is set, so there is no remainder to leave blank. A quantity with an unspoken-for gap is a progress fill wearing segments, and the gap is where a reader starts reading it as one.
• IT IS A COMPOSITION, NOT A FILL. It answers what is the rest of it doing, never how far through am I — which is the question every other money surface in the product refuses.
• THE RAMP IS BUILT ON --primary, NOT --primary-flat. The flat token cannot carry three steps: in dark it resolves to the same color as --primary, and --primary-deep is 1.26:1 from either. Mixing --primary toward --surface-card lets one declaration serve both themes, because the accent and the ground flip together.
• EVERY FIGURE IS ALSO TEXT. The segments run 1.5:1 to 2.7:1 against each other, which is enough to separate them and not enough to carry meaning alone. The key states every amount at full contrast, and the bar is the glance rather than the source.
• The figures sit under the bar, never inside it. A number on a fill is unreadable at both ends.
• No animation. It is a state, not a process.
• Tone names are neutral (.strong/.mid/.faint), not domain words — a caller supplies what strong means. Two tones are fine; not every fixed pool has three states.

Why it is a component

One instance and it settles an argument the deck makes twice: you compare by line, not by quote. A column per candidate and a row per thing means the reader's eye moves along the thing they care about rather than down a document somebody else wrote.

Anatomy

Variants

• .same the line where everything agrees. Stays on screen, quiet.

Rules

• EMPHASIS MARKS A DIFFERENCE, NEVER A WINNER. The product does not choose.
• The row where everything agrees stays on the screen and stays quiet. Removing it leaves the reader unable to tell whether the product looked and found them equal, or never looked.
• Stack, never squeeze: the label takes its own line above the cells rather than becoming a column that shrinks the figures.

Anatomy

Variants

• .default neutral ground
• .off offline. Says what still works, never what broke. No retry.
• .clock A clock is running, and it says so — an eyebrow in --amber-deep, not a clay panel. NOT builder-only, which this entry claimed until it was counted: 9 instances across 8 pages, and 5 of those pages are the homeowner's. What a homeowner screen may not carry is a bare timestamp; the clay itself is fine for a consequence with a date on it, which is what the deletion screen on 15 and the subscription seat on 14 both use it for.
• .who indigo. Somebody else got there first. News about a person, not a failure.
• .gone the thing is not there. Always carries a way back.

Rules

• The action slot is NOT optional. A say with no act is a bug in the page, not a variant.
• It sits above the content and never over it. There is no scrim and no modal in this library.
• There is no red rung. Amber means a clock, never an error.

Anatomy

THE FIRST TWO SLOTS ARE ELEMENTS, NOT CLASSES, and this entry said otherwise until the gallery tried to draw it. It declared .gl and .p; the deck was then counted, and across 47 callouts the .p class appears ZERO times while .gl appears on 23. The CSS is the reason and it was right all along: hc.css styles .callout p, and icons.css styles body.hc-air .callout > svg with the same four declarations .gl carries — 17px, flex none, flex-start, and the same computed first-line offset. So inside a callout the class is redundant, which is why 24 of them omit it and look identical. The 23 that carry it are not wrong, only inconsistent.

Variants

• .c-mute the default. An aside.
• .c-idg an observation the product made
• .c-amber a consequence worth knowing before you act
• .c-coach the coach leaning in, opening a thread rather than reporting one
• .line a row with a count pushed right. Three parts — glyph, label, count.
• .c-sage DECLARED BY NOTHING. 6 instances carry it and no stylesheet on this sheet or in the design package has a rule for it, so it paints exactly what a bare callout paints. Either a tone somebody meant to add or a name that outlived its rule; recorded rather than silently deleted.

Rules

• IT SITS BARE ON THE GROUND, AND THAT IS RUNG 0, NOT THE OUTLINE RUNG. No fill, no radius and no box padding: the outline rung is for a container-shaped absence or a set, and a one-sentence aside is neither. Boxed at the card radius it took the same footprint as the options above it and read as a fourth option the reader had failed to select. The scroll's own block gap is what separates an aside from what it is about.
• A c-coach WITH a heading is a card and becomes a block: the glyph goes on its own line and the text takes the card's own left edge. Actions belong to the card, never to the glyph.
• A callout with a trailing count is a line and stays a row. These two rules are exhaustive; anything else is the default.
• The glyph marks the first line of the paragraph. It is not centered, because it is a mark on prose rather than a marker on a row.

Why it is a component

17 instances, and it is the one component whose content is not the product's. Everything else on a screen is written by HouseChalk; this is a builder's sentence, kept.

Rules

• IT IS A QUOTATION AND IS ALWAYS DRAWN AS ONE, with the marks. The moment it is paraphrased it becomes the product's voice and the component has no reason to exist.
• It is never edited to fit. A long quote runs long.
• It carries no action. What to do about what somebody said belongs to the surface around it.

Not for

• The coach speaking. That is a callout at c-coach.

Why it is a component

It is the loudest thing the library can do, so its whole specification is about when NOT to reach for it. states.css names the entire list and it is three long.

Anatomy

Rules

• THREE REASONS, AND THE LIST IS CLOSED: an invalid token, a client too old to read the data, and the first open of a lapsed account. Everything else that feels urgent is rung 2 with an action on it.
• It replaces the screen rather than covering it. The phones that carry one hold the notch and the block and nothing else — no app bar, no scroll, no scrim.
• z-index 45: over the app's own chrome, under the device.
• It says what still works before it says what stopped. The binder is still here comes before what stops is adding to it.

Rules

• It is a fact about the data, not a status of the screen.
• Never a spinner and never a refresh button.

Rules

• Matches the real layout. A skeleton that does not is a second layout to maintain.
• No shimmer. It is a placeholder, not an animation.

Variants

• .mine answered by you
• .theirs answered by someone else
• .superseded a newer one went out
• .replaced the decision changed
• .withdrawn the sender pulled it
• .expired the date passed

Rules

• Locked is not invalid. Only a token that never existed is a 401; everything else renders and explains itself.
• Every one of them carries a way forward. A dead end is a design failure, not a state.

Why it is a component

An anti-phishing control rather than a decoration. states.css:609 — "they know Dave, they do not know us, and a page leading with a brand a stranger has never heard of reads as smishing."

Rules

• Above the block and never inside it. It is on the LIVE page too, which is why it is not part of lnk.
• Builder first, product mark second and smaller.
• The project line is upper-cased by the component; the deck authors it as prose.
• invalid paints no attribution at all — it has no row to read a sender or a project from, and an empty block is worse than none.

Why it is a component

It is the deck's answer to the disabled control, and the answer is that a disabled thing has to say why. 5 instances, and 3 of them are .reached — the state where the reader has asked and the reason is showing. OWED: 3 of the 6 .ctl carry no why at all (00-states:663, 07:355, 15:881), which is the component's one required part missing. They draw the pill and stay non-interactive until the sentence is written.

Anatomy

Variants

• .reached the reader asked, so the reason is showing. 3 of 5.

Rules

• THE REASON IS ALWAYS PRESENT IN THE MARKUP AND HIDDEN UNTIL ASKED FOR. A disabled control with no explanation is the thing this component exists to replace, and hiding the reason behind a tap is different from not having one.
• It is a card, not a control. Graying out a button says no; this says who can and what you can do instead.
• The reason names a person where there is one: Dave is the only person who can void a change order beats insufficient permissions.

Why it is a component

It is the whole of the deck's offline story and it is nine pixels. Rung 0 says the data renders its own state and nothing is added — so a queued item is not a banner, a toast or a retry button; it is the line it belongs to, wearing a mark.

Rules

• INSIDE THE LINE, NEVER BESIDE IT. Six of the ten sit in a .n and four in a .t-meta. A trailing slot would make it a status the row reports rather than a mark on the sentence, and the row already has a status to report.
• Hollow, not filled. A filled dot in this deck means a state that has settled; this one has not.
• No count, no percentage, no retry. The queue is not a thing the reader manages.
• It disappears on its own. Nothing replaces it and nothing confirms it — the absence of the ring is the confirmation.

Not for

• A failure. Nothing in this library says a send failed, because the product retries and the reader cannot help.

Why it is a component

An empty list is the commonest state in this product and the easiest one to draw as a failure. This is the deck's rule that a finished list is an achievement: it takes the settled mark, not the neutral one, and it says what happened rather than what is missing.

Anatomy

Rules

• SETTLED GROUND, NOT NEUTRAL. This is the state where the reader is finished, and a gray box says the screen is broken.
• It says what happened, with a date where there is one. The last item on your list was closed on 4 October is the sentence; No items is not.
• No illustration and no call to action. There is nothing to do, which is the message.

Not for

• A list that is empty because it has not started yet. That is dated, and it is amber.

Why it is a component

The distinction from empty_y2 is the whole reason both exist, and it is a distinction about time rather than about content. One is finished and one has not begun, and drawing them the same way tells the reader nothing.

Anatomy

Rules

• AMBER MEANS A CLOCK, NOT A WARNING. states.css is explicit that there is no red rung and that heat never rates a state; this ground says time is involved.
• It always carries a date or a trigger. A not yet with no when is worse than an empty box.
• It ends by saying there is nothing for the reader to do. That sentence is the point of the component.

Not for

• A deadline the reader has to meet. A clock running against somebody is rung 2 and says what to do.

Why it is a component

It is the one screen where the shell is always there is false, so the no-spinner rule cannot simply be inherited and has to be restated. Two instances, and the second is the one that matters: the abnormal wait.

Anatomy

Rules

• NO SPINNER, NO PROGRESS BAR, NO MESSAGE while the wait is normal. The product holds its own identity; it does not narrate.
• The late sentence is in the reader's terms — what is happening to them, never what the system is retrying. We are having trouble reaching it rather than a retry count.
• It takes the hero gradient and --on-hero, and that ink does not flip with the theme because this surface does not either.
• z-index 45: above the dock and the scrim, below the notch. A blocking surface covers the app's chrome, which is the point; it does not cover the device.

Why it is a component

It is the smallest component in the library and it carries the product's most load-bearing promise. Two instances, one line each, and no action — because there is nothing the reader can do from here and pretending otherwise would be the whole failure mode.

Rules

• ONE LINE, AND IT SAYS WHAT STAYS. Read-only since 30 June. Everything here stays. The date is not optional; a lapse with no date reads as a threat.
• No action on it. The person who can restart the subscription may not be the person reading, and the block state is where that conversation happens.
• It is rung 1 and it stays rung 1 forever. Only the FIRST open of a lapsed account is allowed to block.

Not for

• The first open after lapsing. That is block, rung 3, and it happens once.

Anatomy

Rules

• The hint explains the ask, never the format. Ten characters minimum is a format; You are joining a company that already exists is an ask.

Rules

• A tick, never a switch. A switch is a preference somebody resets; this is an assertion somebody is held to.
• The sentence rendered is the sentence stored. A record holding a summary, a version number or a link to whatever the wording is today is worth nothing in the only conversation it exists for.
• The marker is centered on the whole sentence, however many lines it runs to.

Why it is a component

Nine instances and every one of them carries a caption, which is the specification: this product does not ship a switch whose effect the reader has to guess.

Anatomy

Variants

• .lock on and not changeable, because a floor applies. 1 of 9. Quiet, not crossed out: --primary-flat, never a disabled gray.

Rules

• THE CAPTION SAYS WHAT HAPPENS, NOT WHAT THE SETTING IS. Off means they hear on Friday like everyone else is a caption; Enable notifications is a label repeated.
• A locked toggle stays visible and stays on. Hiding a floor is how a reader discovers it by being surprised.
• 9 of 9 carry a caption. A toggle without one has not been thought through.
• TOGGLES IN A RUN ARE SEPARATED BY A HAIRLINE, and the first does not take one. --rule-ink separates two rows and is meant to be felt rather than seen — the design package's own definition of the weight, as against --outline for a card's edge and --rail-ink for structure. The 'no dividers between sibling rows' rule is about the heavier line, and the argument that removed this hairline was reading it out of a BRAND.md the package names as superseded.
• The switch centers against the whole block, not against the name's first line.
• A locked switch keeps --primary-flat and never a neutral disabled gray: at #B4B4B4 the track is 2.07:1 on a card and the white thumb is 2.07:1 on the track, both under the 3:1 non-text bar at once, so a reader cannot tell which way it is set. --primary-flat is 4.74:1 on both, and says the true thing — this is ON and you may not move it.

Why it is a component

Two instances on two pages, and it is the only input in the deck that is not a field. Its rationale was rewritten when the second one landed: the first draft said it was here because "the front door is the one surface where the reader is doing something mechanical rather than deciding", which read the component off the only page that had it. The real rule is in _ds/forms.css and it is about consequence, not surface: this is a CONSEQUENCE GATE and never an entry gate. It appears where money moves and the session cannot vouch for who is moving it, which is one frame on the front door and one on a link.

Variants

• .next the box the next digit goes into. Exactly one at a time.
• .on a box that has a digit in it: the accent edge plus a 3px glow at 18%. Defined in _ds/forms.css since the component landed and listed here for the first time under Q236 — the register carried next alone, so the state that says how far you have got was undocumented on every surface that reads this file.

Rules

• Six boxes, always drawn, always the same size. A code entry that grows as you type moves the target.
• One box is marked as next and it is the only affordance. There is no cursor and no keyboard hint.
• No countdown on it. A code that is expiring says so in a line underneath, at rung 1, because a clock ticking on the box is anxiety with no action attached.
• IT NEVER STANDS BETWEEN A PERSON AND THEIR OWN HOUSE. A page putting this in front of a login has misread the model. What it gates is an amendment, and the amendment is always drawn on the same screen as the boxes.

Why it is a component

Ported from the reviewed design-system JSX, props and prompt; decision controls is the first product consumer.

Rules

• Exactly one option is selected.
• Selection uses primary ink and a 1.5px ring, never a fill.
• Wrap options and preserve 44px touch targets.

Variants

• .chip-count a number. 62 uses.
• .chip-status with is-settled (14), is-open (19) or is-waiting (2), and bare once — 47-proof-behind-a-decision.html:339 draws .chip chip-status with no modifier and takes is-open's neutral ink.
• .chip-money a figure. 17 uses.
• .chip-time a date or a deadline, as a fact and never a countdown. 35 uses.
• .chip-code a product code or identifier, monospaced and tracked out — the one chip somebody reads a character at a time. 26 uses, the third most drawn of the set.
• .chip-person who. 3 uses.
• .chip-conflict over, clashing, nobody has this. Terracotta, and reserved for a genuine clash — a price above an allowance is chip-money, not this. 2 uses.

Rules

• A chip may carry an outline; a card may not.
• A chip never carries an action.
• SEMIBOLD, BECAUSE A CHIP IS NOT PROSE. 12px at 600, line-height 1, in a 4px-by-8px pill. Q230: the weight went to the design package, the padding to the deck, and the app was drawing the pill at exactly double on both axes.
• A chip may carry a leading glyph and no page does. .chip's gap: 4px has nothing to space in any of the 181 real instances, and HcChip has no slot for one.

Why it is a component

99 instances and the deck's only icon container. It is also where a rule that is stated in the CSS has never been stated in the library: the box gets a background only when the background is carrying a state.

Anatomy

Variants

• .done a settled ground. DEFINED AND DRAWN ZERO TIMES.
• .waiting a waiting ground. DEFINED AND DRAWN ZERO TIMES. It was called warn until Q222: this note already said "waiting", the stylesheet comment above it already said "the ink carries the clock", and the app's one real call site already drew a clock — only the class name said otherwise. warn is the word the design package struck from Option for the same reason, and a ground here means a state rather than a judgment.
• .ic-first lifts the box onto the first line of prose beside it. One use.

Rules

• The box is 32px whether or not a background appears, so a row with a state marker and a row without line up.
• A GROUND MEANS A STATE AND NOTHING ELSE. icons.css says it outright — 'if the color is not carrying a state, the glyph is bare' — and there are exactly two states it may carry, settled and waiting.
• It is centered on the row, however many lines the name runs to. .ic-first is the exception and it is for prose, where the glyph marks the first line rather than the block.
• THE TWO STATE GROUNDS ARE UNUSED AND ONE PAGE REINVENTED THEM. .ic.done and .ic.waiting are defined and drawn zero times, while 03-underneath-and-home puts a .tick inside the box on 14 rows to say settled, open or waiting — a nested dot doing the job the ground was built for. Two mechanisms for one idea, and the unused one is the library's. Worth settling before either is built on.
• THE GLYPH IS 16, NOT 17. The prose in icons.css said 17 while all three declarations under it said 16; the design package draws 17 and 16 is the rung, which is how a deck measurement enters the library. The app was drawing 24 — the wrong constant entirely, under a comment claiming 16.

Not for

• A marker you can act on. That is mark, which is round and 19px and belongs to a choice.

Why it is a component

It is the one marker a person acts on, and it was drawn at 17, 18 and 18px on its three sites with a hand-nudge each before icons.css settled it. Its size is derived rather than picked: 19px against a 15px label is the 1.27 ratio that makes a marker read as a control instead of a bullet.

Anatomy

Variants

• .mark-lg 24px with a 14px tick, for a 19px title. Holds the same ratio at larger type. 5 uses.
• .on chosen. Takes the accent ground.
• .mark-glyph an svg whose own artwork carries the ring, so it needs no ground. Same 19px footprint. 2 uses.

Rules

• ALWAYS CENTERED on the row it marks. It belongs to the whole option rather than to its first line, which is the opposite of a glyph on prose.
• It is sized by the type it marks, not by preference: 19px against a 15px label, 24px against a 19px one.
• An empty marker is a real state and draws nothing but its ground. There is no third state.

Not for

• Labeling a row. A marker that cannot be chosen is an ic.

Why it is a component

It is the deck's only marker that is neither a status nor a count, and the distinction is load-bearing: a chip reports, a pill answers. 15 of the 56 are ticked, which is the whole reason it is not a chip.

Variants

• .pill-on chosen. Success ground. 15 uses.
• .pill-idg indigo. DEFINED AND DRAWN ZERO TIMES.

Rules

• A pill can be chosen; a chip cannot. That is the whole difference and it decides which to reach for.
• It carries a phrase, not a figure. A number in a pill is a chip wearing the wrong shape.
• No outline. The ground is the separation, the same rule a tinted card follows.

Not for

• A status. chip-status says settled or open, and it is never tappable.

Variants

• .cta-ghost the quiet way out. The primary's geometry, transparent ground, accent ink, centered.
• .cta-outline a committing action that must remain visibly a button without taking the filled primary weight. Full-width, transparent, with the role-accent outline.

Rules

• One primary per screen. A second one is two screens.
• A destructive action never takes the filled primary weight. After its consequence is stated, it takes the outline.
• Ghost is for a quiet way out, not for a state-changing commit.
• The ghost is centered. Hung off the left margin it reads as a stray link.

Why it is a component

148 instances and the most uniform thing in the deck: every single one holds exactly one svg and nothing else. A component that is already unanimous is cheap to specify and expensive to leave unspecified, because the first exception will look like a local decision.

Anatomy

Rules

• Exactly one glyph. Never a label beside it, never a badge on it.
• It lives in an app bar's trailing slot, with one exception: the back chevron takes the leading slot on the 19 bars where nothing else holds it. A round button elsewhere on a screen is a cta or a row's affordance, not this.

Not for

• A count. A number beside an icon is a chip, and it goes in a row's trailing slot.

Why it is a component

Ported from the reviewed design-system JSX, props and prompt; decision controls is the first product consumer.

Rules

• Primary ink, semibold, underlined, at least 44px.
• Disclosure exposes its expanded state.
• The primary screen action remains Cta.

Why it is a component

It is the only component in the deck that draws time as a line, and the rail down its left is the one place a line in this product is allowed to be structure rather than a whisper.

Anatomy

Rules

• THE RAIL IS STRUCTURE AND CARRIES MORE WEIGHT THAN A DIVIDER. It is the line the eye follows down the timeline, at --rail-ink rather than the --rule-ink used between rows.
• The node that matters is the one that has not happened. Settled nodes above it collapse, because four of them push the next one off the screen.
• Every node carries a date or the thing it depends on. Releases when the final inspection passes on 24 June, not on a date of its own is a node; Next alone is not.

Why it is a component

29 instances and the shape a homeowner navigates by. It also carries the deck's clearest naming trap, below.

Anatomy

Variants

• .empty no picture yet. 13 of 29 — nearly half, and the ordinary case on day one.
• .full spans the whole grid row. 2 uses.

Rules

• empty AND full ARE NOT OPPOSITES AND THE NAMES SUGGEST THEY ARE. empty means the room has no picture; full means the card spans the grid — grid-column: 1 / -1. room empty full is a real and correct combination: a room with no picture, drawn wide. Nothing else in the library has two modifiers that read as a contradiction.
• A room without a picture is drawn at the same size as one with. Half the board is empty on day one and a ragged grid says the product is broken rather than new.
• The name is always present. The picture never replaces it.

Not for

• A decision inside a room. Rooms are the way in; decisions are rows.

Why it is a component

One instance, and it is specified because the next document surface will be built from it. It is the only place in the deck where the product shows something it did not draw.

Anatomy

Rules

• The well is darker than the page ground, so the sheet reads as a physical thing on a surface rather than as part of the app.
• The sheet keeps its own aspect ratio. A document cropped to fit is a document the reader cannot trust.
• No annotation layer, no markup tools. This shows a paper; it does not edit one.

Why it is a component

149 uses across the deck, its own stylesheet and five variants, and the library had no entry for it. It surfaced only when cold needed to name what it holds — which is the argument for specifying components by walking the deck rather than by listing what comes to mind.

Variants

• .logo-mark the mark alone. 143 uses, almost always in an app bar's .brand.
• .logo-wordmark the name alone. 2 uses, both on the cold start under the mark.
• .logo-lockup mark and name together. 1 use.
• .logo-builder-lockup the builder's lockup. 1 use.
• .on-hero swaps to the white artwork on a hero gradient, where the surface does not flip with the theme. 2 uses.

Rules

• It is a background image on an empty element, never an <img> and never inline SVG. That is what lets a variant be a class rather than a different file in the markup.
• ON A HERO GRADIENT IT TAKES .on-hero, because that surface does not flip with the theme and the default artwork would vanish on it.
• The mark alone in an app bar; the lockup only where the product is introducing itself.

Not for

• Decoration. It appears where the product identifies itself and nowhere else.