Shared components, accessibility, security, data fetching, live-collection identity, animation, styling, typography, and how a builtin app gets discovered. Page structure is in page-layout; color and CSS-var rules are in theming-contract; user-facing strings are in i18n-catalog.
React 18, Redux Toolkit, React Query (@tanstack/react-query), React Router v7,
Framer Motion, Tailwind CSS 4, Lucide React, DOMPurify, highlight.js, the Pierre
editor (src/pierre/), TypeScript, Vite 8. Read the pins from website/package.json rather than this list.
Prefer the library already here over a new dependency. Every addition is bytes in a bundle a user downloads and a supply-chain surface someone has to review, and two libraries doing one job is how a codebase ends up with two animation systems whose transitions do not compose.
The dashboard is a sovereign surface: used daily with full attention, so it is dense, keyboard-friendly and muted. Dialogs, settings and onboarding are transient surfaces: used occasionally, so they are spacious and self-evident. Judge a design against the kind of surface it is; the UX review lane applies the same standard.
Chrome, Firefox, Safari and Edge. Use standard Web APIs only, and guard the
browser-specific ones (typeof Notification !== 'undefined'): an unguarded API
throws at module scope, so the page renders blank rather than degrading.
Text inside a React-rendered subtree (react-markdown output, the chat bubbles,
the markdown preview) is painted with the CSS Custom Highlight API
(CSS.highlights + Range, styled by ::highlight()), never by inserting a
<mark> around it: splitting a React-owned text node breaks the next React
commit that touches it. The API needs Chrome/Edge 105, Safari 17.2 or Firefox
140; older browsers paint no highlight, while match counting and stepping to
the current match keep working (utils/domHighlight.ts).
Pierre draws a fenced code block into a shadow root. A TreeWalker never
enters it, and a document selection reports a drag inside it as collapsed.
utils/pierreShadow.ts therefore reads the block's source lines for the preview
find, which needs no API newer than the one above, and resolves a selection with
Selection.getComposedRanges, which needs Chrome/Edge 137, Safari 17 or
Firefox 142; older browsers open no selection toolbar over a code block.
SelectionToolbar takes such a selection only from a host that passes
codeSelection (the file panel's markdown preview), because the other hosts'
comment anchors cannot resolve it.
src/components/ui.tsx is the primitive set. Compose from it rather than
hand-rolling:
Card, CardTitle, Btn, SendBtn, IconButton, IconButtonGroup, Input,
SearchInput, Badge, SourceBadge, StatCard, Skeleton,
ContentSkeleton, SkeletonToggleRow, SkeletonField, SkeletonInfoRow,
FormSkeleton, EmptyState, PanelSectionHeader, PageHeader, Toggle,
Slider, Checkbox, FilteredEmpty.
There is deliberately no Select primitive: use SimpleSelect,
SettingsSelect, SearchableSelect, or SettingsMultiSelect for a searchable
checkbox list in Settings.
SimpleSelect accepts optional decorative optionIcons alongside its text
labels. Desktop rows and the selected value show those identities; touch devices
retain the native text option list and show the selected icon beside the control.
An icon does not replace the option's accessible name or typeahead text.
The provenance pill is SourceBadge, not a badge named after any one source.
Two implementations exist on purpose:
ui.tsx's takes a required source string plus optional children (a label
shown instead of the raw value), tone ('auto' | 'neutral', which forces the
grey style) and title; SimpleSelect's optionBadges renders it with a badge's
hint forwarded to title;
components/SourceBadge.tsx's takes an optional source plus children, so a
caller can render highlighted or translated label content over the same color
mapping. Both fall back to a neutral pill for an unrecognized source, so a new
source value degrades rather than throwing.
PanelSectionHeader is the one idiom for a counted list-section header inside a
side panel (label, count node, hairline rule). Route a new panel section through
it. The Files and Artifacts tabs each grew their own and silently diverged on
case, size, color, and whether the count was a node or punctuation baked into the
translated label.
Other shared modules:
ErrorNotice.tsx(error text and its opt-in agent hand-off). In a height-constrained block notice,scrollMessagemakes only the message scroll, keeping the built-in hand-off outside that scroller. UseactionPlacement="below"to keep the hand-off on its own line; the host owns the height constraint and any separate recovery controls. The option defaults to false and has no effect on inline notices.messageClassNamealone cannot constrain the text column's height while reserving room for the hand-off.messagePlacementis'beside'by default;'below'puts the raw message on its own line under a plain-languagetitle, and is ignored without atitle.Clickable.tsx(accessible clickable div; see below)SegmentedControl.tsx(sliding pill, Framer Motion) — see the switcher rule below. It is a WAI-ARIA radiogroup: each segment isrole="radio"witharia-checkedand a rovingtabIndex; arrow keys, Home and End move focus without committing a value, and disabled segments are skipped.ariaLabel/ariaDescribedBylabel the group, andwraplets full labels wrap rather than hiding themui/tabs.tsx,Tablist.tsx,ui/tabsPill.ts(the other two switchers and their shared class recipe) — see the switcher rule belowDetailPanel.tsx(resizable side panel with animated open/close)SidePanelLayout.tsx(shared side-panel page layout)AgentSelector.tsx(portal dropdown with ARIA)layout.ts(LAYOUTnumeric constants: nav widths, sidebar width, max message width, topbar height, log line cap)InfoTip.tsx(the one help-tip pattern: hover or focus reveals, click or tap pins, Escape dismisses, and the tip text is the glyph's accessible description — see below),MarkdownRenderer.tsx(the markdown renderer, with highlight.js syntax highlighting; its owners are mapped below),TypewriterText.tsxResizeHandle.tsx+hooks/useColumnResize(the drag grip between two PANES)ColumnResizer.tsx+hooks/useTableColumnWidths(the drag grip on a TABLE column) — see below
A data table whose values get truncated lets the user drag its column
boundaries: useTableColumnWidths(storageKey, specs) holds the overrides (one
localStorage key per table) and <ColumnResizer> is the grip. On a ui/table
table, render the header cell as ResizableTableHead, or pass style and
resizer to SortableTableHead; both live in SortableHeader.tsx. Rendered markdown tables are the
second ColumnResizer consumer, through components/markdown/useMarkdownTableColumns.tsx.
It assumes a fixed-layout table in the shape the Schedule jobs table
documents: every resizable column declares a px width, exactly one column
declares none and absorbs the spare, and the table's min-width is the px
columns plus a floor for that residual. Three rules follow, and the first two
are what a review should check:
- Move the table's
min-widthbycols.extra. A fixed layout does not shrink content to fit, so a column that grows whilemin-widthstands still takes its pixels out of the residual column and draws that column's content over its neighbour. Widening a column must cost horizontal scroll, never another column. - Each
baserestates that column'sw-[Npx]class, and a test holds them equal (SchedulePage.columnContract.test.tsis the model). The classes stay the source of the defaults, so an untouched table renders exactly as it did before it was resizable:style()returnsundefinedandextrais0. - Leave the residual, a checkbox gutter and a pinned
stickycolumn fixed. The residual has no width to drag, and a pinned column's overflow cue anchors on its literal width.
An auto-layout table cannot adopt this by adding grips: there a width is a hint the browser renegotiates against content, so a drag would not track the pointer. Migrate it to the fixed-layout shape first.
A resizable header cell spells relative in its own class string, literally:
the grip is absolutely positioned and resolves against the nearest positioned
ancestor, and shadcn/require-static-classes rejects a className a
design-system component builds from an opaque value -- so the header components
pass className through untouched and the column-contract test holds every
resizable header to it.
The grip is the ARIA window-splitter widget (focusable, arrow keys, Enter or a
double-click to reset one column). Because it is focusable content with its own
label, a header cell that hosts one needs aria-labelledby pointing at its
visible label, or the grip's name is appended to the column header and announced
with every cell. The two header components above already do this.
src/kirocrew-ui/index.ts re-exports the subset that apps may import as
@kirocrew/app-sdk/ui. Adding a primitive there makes it app-facing API, so add
deliberately.
src/app-sdk/ChatEmbed.tsx keeps its composer markup small but delegates draft
behavior to app-sdk/useComposerDraft. Its textarea attaches the hook's
textareaRef, so Enter sends, Shift+Enter inserts a newline, IME commits do
not send, and the draft grows to the shared 240px cap before scrolling. Do not
reimplement those key or sizing rules inside the component.
Stories for these primitives live in src/stories/ and render them in isolation
under every theme (npm run storybook); see
testing § Component stories. Seven primitives have
one today. A story is the cheapest place to look at a new variant or prop, so add
or update one when you touch a primitive that has one; a per-primitive
requirement is not in force until the change that makes CI render stories.
A control's caption carries two kinds of prose, and the Settings primitives
(settings.tsx) give each its own prop. description stays on the row at all
times; it is for the sentence a reader needs to MAKE the choice — a consequence,
a cost, where data goes, a status such as "disabled by instance config". hint
renders an InfoTip beside the label; it is for what the control IS, which a
reader wants once and never again. A row that always shows two lines of prose
spends attention whether or not it is being read, so the default for an
explanatory sentence is hint, one catalog string per tip. An error is neither: it renders through
ErrorNotice (AUTOSDE.yaml, errors-use-error-notice), never behind a tip.
InfoTip is accessible by construction — keyboard focusable, named by a short
generic phrase, described by the tip text (the open tooltip, or title while it
is closed), pinnable by tap for touch — so a surface outside Settings reaches
for the same component rather than a bare title attribute or a hand-rolled
hover.
InstantTip does not show its hint on a touch tap: the mouse events a browser
replays for a tap are ignored, because a hint appearing mid-tap can cost the click
(a real mouse on a touch device still hovers). An anchor whose bubble outranks its
click — one with no click action, or whose tip carries a warning the user must see
before acting — opts in with openOnTap.
components/MarkdownRenderer.tsx is the renderer's only import path. Its default
export (the memoized component), its named exports and its module id are what
the consumers import and what about 150 specs mock, so all three stay there. It
is also the composition root: what has to be decided in one place lives in it,
and every other concern has one owner under components/markdown/.
| Owner | Holds |
|---|---|
MarkdownRenderer.tsx |
the ordered remark and rehype chains, and the parser built from them that the source repairs read (AUTOLINK_PARSER); MD_COMPONENTS, the element-to-renderer map, with the fence code override and the link overrides MdAnchor / MdParagraph; the per-block source passes and their order (MarkdownBlock); fence dispatch (BlockRenderer); the root component and its providers |
markdown/contexts.ts |
every context the pipeline's modules share, each created once; the facade re-exports the six public ones (MediaApprovedCtx stays private to markdown/remoteMedia.tsx, which both provides and reads it) |
markdown/linkTargets.ts, markdown/pathReferences.ts |
what a link or code span points at: artifact routes, unfurl eligibility, open sessions, sidebar folder paths (folder-chip resolution); path candidates, file:line suffixes, probe resolution and activation |
markdown/sanitize.ts |
the tag and attribute allowlist (rehypeSanitize) and remarkVerbatimUnknownTags |
markdown/treeTransforms.ts |
fenced-code marking, block unwrapping, soft breaks, source positions, position-stable root keys |
markdown/streamingEffects.ts |
the streaming tail's glow, reveal and caret |
markdown/linkBoundaryRepair.ts |
the source-level link repairs gated on remark's own parse: CJK autolink boundaries and refused link destinations |
markdown/elements.tsx |
the restyle-only element overrides and the sanitizer-derived attribute forwarding they share (sp / spa) |
markdown/typography.ts |
the heading, list, table-cell and inline-run class strings markdown/elements.tsx and the Office preview's OfficeBlockList (FileRenderers.tsx) both render; markdownTypographyParity.test.tsx pins the two surfaces to it |
markdown/InlineCode.tsx, markdown/copyFeedback.tsx |
the inline-code chips (path, session, work item, sidebar folder (FolderChip), copy) and the copy outcome every chip shares |
markdown/MarkdownTable.tsx |
a table, its Markdown / CSV copy row, and the Widen / Narrow toggle |
markdown/useMarkdownTableColumns.tsx |
resizable table columns (the second ColumnResizer consumer) |
markdown/markdownSniff.ts |
whether an untagged or generic-tagged fence holds a markdown document, so the transcript may offer it the Formatted | Raw card |
markdown/ImgWithFallback.tsx, markdown/remoteMedia.tsx |
images (local-path routing, the layout reserve, the broken-image chip) and the click-to-load gate for remote images, video and audio |
markdown/MermaidBlock.tsx |
lazily loaded mermaid, its initialize config (securityLevel: 'strict'), and the diagram's box and font gates, source view and downloads |
markdown/Lightbox.tsx |
the image viewer and dispatchLightbox |
Imports run one way. The facade imports the owners, and nothing under
components/markdown/ imports the facade: a module that did would receive the
stub in every spec that mocks the renderer. Consumers keep importing from the
facade for the same reason. The one exception is markdown/typography.ts, which
FileRenderers.tsx imports directly: it is plain data with no imports of its
own, and reading it through the facade would hand the Office preview the
renderer's stub in every spec that mocks the renderer. Three things must stay in the facade's own text: the
seven remark/rehype package imports (test/test_source_providers.py pins that
set against the backend converter), import '../utils/hljs'
(hljsCoreOnly.test.ts), and the two lines the i18n added-line gate counts, in
MdAnchor and stripStrayToolUseTags.
components/MarkdownPanel.tsx (a side-panel file tab), components/ChatPane.tsx
(one chat session in split view or a mate's chat) and
components/WebPreviewPanel.tsx (the Browser tab) are facades over sibling owners
in components/. Each facade keeps its module id, its default export and every
named export: hosts import it, and the specs that mount a host mock it by that id,
so a consumer never imports an owner. Imports run one way, from the facade to its
owners. Each owner hook is called once per render at a fixed place in its facade,
so the panel's effects keep one order.
| Owner | Holds |
|---|---|
MarkdownPanel.tsx |
Props, the panel and its two layouts (side panel, full screen), the edit, save, close and navigate guards, comment drafts and their anchor highlight, the line reveal |
MarkdownPanelHeader.tsx |
the header's controls: the breadcrumb, the artifact and knowledge toggles, the ⋯ menu |
useMarkdownPanelFileState.ts |
the file's knowledge-library and artifact-library state |
MarkdownPanelBody.tsx |
the body's blocks: comment hint, missing-file banner, empty-diff notice, diff view, comment overlay, find bar |
markdownPanelSourcePos.ts |
where a selection sits in the source (resolveSourcePos, findCoords) |
useMarkdownPanelFind.ts |
the CSS Custom Highlight registry and preview find (Cmd+F) |
useMarkdownPanelDisk.ts |
the disk truth (the panel's reads, the catch-up latch, the watch, the missing-file retry, the last-copy rescue) and the working-tree diff against HEAD |
useImageBoxComments.tsx |
image box comments: the box draft and its typed text (useImageBoxDraft), and the host the rendered images read plus the box composer (useImageBoxHost) |
useCommentHint.ts |
who sees the comment hint, with which wording, and its New badge |
ChatPane.tsx |
the pane's layout and dock, its store reads, the follow-up chips, the queue-card actions, and the transcript mount (transcript={{ … }}) |
ChatPaneProps.ts |
the props interface and PaneLeading |
useChatPaneDraft.ts |
the pane-local composer draft, parked and restored per slot |
useChatPaneUploads.ts |
uploads, drops, and their per-slot notices |
useChatPanePickers.ts, ChatPanePickerMenus.tsx |
the agent and model pickers' data and actions, and their two portaled menus |
useChatPaneSend.ts |
send, steer, the slash commands the pane intercepts, the message quote, the question card's one-click answer (its 404 fallback, onFallbackSend, stays in ChatPane.tsx) |
useChatPaneTurnControl.ts |
the Stop press protocol and the run-state reconciliation |
useChatPaneContinue.ts |
the pane's side of Resume: the composer's and the newest error row's offer for the pane's own slot, and the notice when the gateway refuses it. The press and its spinner are hooks/useContinuePress.ts, the one ChatPage's useTurnRecovery uses too |
ChatPaneTranscript.tsx |
the transcript row set and the rows above the first message |
WebPreviewPanel.tsx |
the panel: address bar, frame, device presets, liveness probe, launcher, the CLI browser view |
webPreviewPanelUrl.ts |
what a target may be: URL coercion, the loopback and embed rules, the self-origin check, the session feed (setSessionPreviewUrl, setSessionPreviewPending) |
useWebPreviewPanelAnnotate.ts |
Annotate: per-slot notes on picks in the native page |
WebPreviewPanelNativeSurface.tsx |
the native browse surface |
New work for a responsibility in the table goes to its owner, and work that
belongs to none of them starts in the facade. Two kinds of line stay in a
facade's own text: the ones the i18n added-line gate counts (the comment-highlight
paint rules in MarkdownPanel.tsx; DEVICE_PRESETS and RELOAD_PARAM in
WebPreviewPanel.tsx), and the constructs a source-reading spec pins there (in
ChatPane.tsx the transcript and dock wiring and the question card's
onFallbackSend with answerRejectedMessage; in MarkdownPanel.tsx the reveal
effect, the header's onToggleDiffSplit call site and the pathBasename use).
Three components render the same pill, because a user should see one control for "change what I am looking at". They are not interchangeable, and the choice is about ACCESSIBILITY SHAPE, not looks:
| Use | When | Why not the others |
|---|---|---|
ui/tabs.tsx (Radix) |
Each tab owns its own panel | The only one that wires aria-controls ⇄ aria-labelledby, so the panel is announced as the tab's. It emits aria-controls UNCONDITIONALLY, so a TabsList with no matching TabsContent points every trigger at an element that does not exist |
Tablist.tsx |
Navigation, but the body below is ONE shared subtree parameterised by the active tab (see WebhooksPage) |
A tablist and nothing else. Use it exactly where Radix's unconditional aria-controls would dangle; aria-controls is recommended by WAI-ARIA, not required |
SegmentedControl.tsx |
A FILTER over one view — which subset am I looking at | Not navigation: no panel relationship, and it measures its parent to collapse to icons then a dropdown, which the two above do not |
All three take their metrics from ui/tabsPill.ts, so they cannot drift apart
visually — src/test/tabsPillParity.test.tsx pins that. Do NOT hand-roll a
fourth: a border-b-2 row of buttons has no keyboard model and no selected state
for assistive tech, which is the defect this consolidation removed.
Radix Tabs uses a static selected indicator when reduced motion is requested. Setting a shared-layout spring's duration to zero still permits projection transforms; those can cover another tab after a layout change. Memory record selection panels and cards likewise disable layout projection in this mode. The rail owns the stacking context for its indicators, so a sliding background stays behind every tab label while crossing between segments.
A navigation rail sits in TABS_RAIL_ROW_CLASS (rail, rule, then content). The
rule is load-bearing rather than decoration: it is the only thing telling a
navigation rail apart from a filter pill, and the System page stacks both.
pages/settings/AboutPanel.tsx (Settings ▸ About), pages/settings/ChatPanel.tsx
(Settings ▸ Chat) and pages/settings/McpManagement.tsx (Settings ▸ Developer ▸
MCP Management) are facades over sibling owners in pages/settings/. Each facade keeps its
module id and every export, so hosts and the specs that mock a panel keep naming the
facade. Nothing outside a panel's own files imports one of its owners, and no owner
imports its facade; the only edges between owners are AboutPanelGatewayUpdate.tsx to
AboutPanelUpdateFlow.tsx, the three useChatPanel* hooks to chatPanelOptions.ts, and
the two MCP views to mcpManagementModel.ts. A facade calls each owner hook once per
render, in a fixed place among its own hooks, so each panel registers its hooks in one
fixed order.
| Owner | Holds |
|---|---|
AboutPanel.tsx |
the panel: the identity hero and both channel switchers, the desktop update card and its errors (UPDATE_ERROR_KEYS), the auto-download and auto-update switches |
AboutPanelUpdateFlow.tsx |
InAppUpdateFlow (arm, approve on the host, apply), AgentUpdateRequestCard, RestartGatewayButton, copyCommand |
AboutPanelGatewayUpdate.tsx |
a gateway install's update flow: its state hook, the Updates card body, the apply confirm |
ChatPanel.tsx |
the rail (railItems), every page's case with its controls, the save-error banner, the composer, About-you and session toggles' state |
chatPanelOptions.ts |
option tables, bounds and the config shapes the controls read |
ChatPanelLinkPatternsEditor.tsx |
the dashboard.link_patterns rule editor |
useChatPanelDashboard.ts |
the dashboardConfig read and writes, Feature Tips and the feature-video readout |
useChatPanelTypedFields.ts |
the draft-backed number and path fields (Advanced, Sessions) |
useChatPanelModels.ts |
the Model page: fallback models, defaults, selectable models, the agent-pin notice, per-role rows |
McpManagement.tsx |
the page: the view tabs, the sharing and pre-resolve cards, the servers table, the Share all list |
mcpManagementModel.ts |
wire types, error-key tables, the row-state derivation and the sharing-evidence verdict |
McpManagementLaunchReview.tsx |
a row's share button, its Details (the agents that declare it), and its hint |
McpManagementAssessment.tsx |
the Sharing assessment view and its Measure control |
New work for a responsibility in the table goes to its owner, and work that belongs
to none of them starts in the facade. Three kinds of construct stay in a facade's own
text, because a generator or a gate reads them there: every Settings* primitive and
settings-search anchor (website/scripts/settingsExtract.ts maps files by name), the
Chat rail's railItems (website/scripts/gen-ui-index.mjs), and the lines the i18n
and unit-literal added-line gates count. The tier labels and the contrary-tier set
that test/test_mcp_shareability_frontend_parity.py pins live in
mcpManagementModel.ts.
pages/settings/SecurityPanel.tsx (Settings ▸ Security) and
pages/settings/RemoteCrewPanel.tsx (Settings ▸ Remote Crew) are facades over sibling
owners in pages/settings/, with the same contract as the panels above: each facade
keeps its module id and re-exports every name callers import from it, nothing outside
a panel's own files imports one of its owners, and no owner imports its facade. Every
component moved whole, so each one registers its hooks in its BASE order.
| Owner | Holds |
|---|---|
SecurityPanel.tsx |
the rail: SECURITY_SECTIONS, SECTION_LABEL_KEY (read by gen-ui-index.mjs), SECTION_GROUP_KEY, the rail summaries, the panel, and the Documentation section |
SecurityPanelPosture.tsx |
Live security posture, and the status row and chip the tailnet card reuses |
SecurityPanelApprovals.tsx |
the ad-hoc auto-approve duration card |
SecurityPanelDeniedCommands.tsx |
Denied commands: the built-in rules by category, the custom deny patterns, the pinned and floor tooltip keys |
SecurityPanelTailnet.tsx |
the tailnet origin card and TAILNET_STATE_KEY, which the rail summary reads |
SecurityPanelTrust.tsx |
third-party app trust grants, per-registry Git-identity trust grants, and their failure messages |
SecurityPanelRedaction.tsx |
the credential-redaction switch, the allowed long-query hosts, RedactionSection |
SecurityPanelLayers.tsx |
the defense-in-depth layer registry (FEATURES and its catalog keys) and its section |
SecurityPanelGovernance.tsx |
the governance-policy viewer, its scope labels and planes, the central-distribution block |
RemoteCrewPanel.tsx |
the panel component: both tabs, every query and mutation, the launch form |
remoteCrewPanelModel.ts |
launch-job predicates, the remembered launch-form keys, the size tiers, the sign-in failure sentences |
RemoteCrewPanelLaunch.tsx |
the setup tab's size, provisioner and prerequisite cards, the launch progress card, the sign-in block |
RemoteCrewPanelCrewRow.tsx |
one crew row (badges, lifecycle actions, inline edit) and the fargate turn-API URL field |
The edges between owners are SecurityPanelTailnet.tsx to SecurityPanelPosture.tsx,
SecurityPanelGovernance.tsx to SecurityPanelDeniedCommands.tsx,
SecurityPanelDeniedCommands.tsx to SecurityPanelTrust.tsx, and the two Remote Crew
component owners to remoteCrewPanelModel.ts (with RemoteCrewPanelCrewRow.tsx to
RemoteCrewPanelLaunch.tsx for the sign-in block). Unlike the panels above, these
owners keep their own Settings* primitives and settings-search anchors: each .tsx
owner is mapped to its facade's tab in PANEL_TAB_MAP
(website/scripts/settingsExtract.ts), so the extractor and the manual-anchor check
read them where they are. The size tiers test/test_cloud_sizes_ui_parity.py pins
live in remoteCrewPanelModel.ts.
Every interactive element MUST be keyboard accessible. Use Clickable from
src/components/Clickable.tsx instead of <div onClick>; it applies
role="button", tabIndex, Enter/Space handling and aria-disabled together, so
the three can never drift apart.
// Good
import Clickable from '../components/Clickable'
<Clickable onClick={handler} className="...">Click me</Clickable>
// Bad: not keyboard accessible, fails jsx-a11y lint
<div onClick={handler} className="...">Click me</div>Clickable self-activates only on keydowns whose target is the element itself,
never ones bubbling up from a focusable descendant. Without that guard a container
would hijack a nested control's native activation, and its preventDefault()
would swallow spaces typed into a nested input.
For an animated interactive element, wrap Clickable with Framer Motion. It
forwards refs and spreads props, so animation and a11y compose:
import { motion } from 'framer-motion'
import Clickable from '../components/Clickable'
const MotionClickable = motion.create(Clickable)Rules:
- Never
<div onClick>or<span onClick>withoutrole="button"+tabIndex+onKeyDown. PreferClickable, which handles all three. - Every icon-only button needs an
aria-labeldescribing the action. - Modals need
role="dialog",aria-modal="true", anaria-label, Escape dismissal, and a focus trap.Modalcarries all four, plus keyboard isolation from the page's global chords — but that isolation follows the React tree, so an overlay rendered as a sibling of<Modal>is outside it. See Keyboard isolation. - Dynamic content that updates in place (streaming messages, notifications) uses
aria-live="polite". - A navigation rail (a column of buttons that each open a section or page) gives the
row of the open destination
aria-current="page"and no other row. A class or an inline style alone paints the row, and assistive technology cannot read it. A list that has opened nothing yet, such as the phone's root list inSidePanelLayout, has no current row. The open row of a list inside one view takesaria-current="true". - Do not use a raw
<button>. UseBtn/SendBtn/IconButton(which carry the styling), orClickablefor a div-based control.
Tooling: eslint-plugin-jsx-a11y reports violations at lint time, and
@axe-core/react scans the live DOM in dev mode (findings land in the browser
console). Neither replaces a keyboard pass over a new control.
The page binds its global shortcuts on a bubble-phase document keydown
listener (useKeyboardShortcuts), and several chords deliberately fire while an
input has focus — the Ctrl+digit session jumps and the Settings chord among
them. A dialog holding unsaved input must stop those chords, or one mistyped
Ctrl+digit navigates away and unmounts the dialog with the draft still in it.
Modal owns that boundary for its consumers: ModalDialog puts a bubble-phase
onKeyDown on the dialog panel, so every Modal consumer inherits it
without wiring anything.
The boundary follows the REACT tree — not the DOM tree, and not the stacking order. React routes synthetic events through the React tree even across a portal, so what decides coverage is where a component sits in JSX:
<Modal open={open} onClose={close} title="…">
…
<SimpleSelect … /> {/* COVERED: a React descendant. Its popup portals to */}
</Modal> {/* the body-level overlay root at z-[9999], and is */}
{/* still covered, */}
{/* because coverage is about the React tree. */}
{pickerOpen && (
<ProjectPicker … /> {/* NOT COVERED: a React SIBLING. It paints above the */}
)} {/* dialog but Modal's panel handler is not an ancestor */}
{/* on its dispatch path, so it needs its OWN boundary. */}Both of those overlays portal to the body-level overlay root (see Floating
layers and Crew switches below) and both paint above the dialog
at the same z-[9999]. Only one of them is inside the boundary. Sharing a
stacking context is a paint-order fact and implies nothing about event
routing — conflating the two is what kept #6833 open, so do not reason about
coverage from a z-index.
A dialog rendered inside the App root rather than portalled to the body level
shares the shell's stacking context, so it uses the z-[65] band: above the chat
chrome (at most z-[63]) and below the z-[100] shell takeover layer, which a tie
would otherwise cover by document order. src/components/AppRootDialogZIndex.test.tsx
pins it. Modal's own z-[100] is correct because it portals.
When you add an overlay that must appear above a dialog:
- Prefer rendering it inside the
<Modal>'s children. It then inherits the boundary, and nothing further is needed. A portal still escapes an ancestor'sclip-path/transform/filter, so being a React descendant costs you no stacking freedom. - If it must be a sibling — because it anchors to something outside the
dialog, or its lifecycle is owned above it — give its portal root the same
guard.
ProjectPickeris the reference implementation:
const isolateKeys = (e: React.KeyboardEvent) => {
if (e.key === 'Escape') { ime.claimKey(e); return }
e.stopPropagation()
}
return <OverlayPortal><div onKeyDown={isolateKeys} …>…</div></OverlayPortal>Three properties of that guard are load-bearing:
- Bubble phase, on the overlay's own root. Capture-phase listeners must keep
receiving keys: the Tab trap (
useDialogFocusTrap, window capture) and list navigation (useListKeyboardNav, document capture) both run before the event reaches the target. A guard moved to capture phase, or ontodocument, would pass a naive test while silently killing arrow-key navigation and the trap. - Escape is excepted.
Modal's own dismissal is a bubble-phasewindowlistener, andstopPropagation()on a synthetic event stops the native event too — so a blanket stop breaks dismissal rather than isolating it. Leave Escape exactly as you found it and let the overlay's own dismissal path own it. - An Escape the IME owns is claimed, not forwarded. Mid-composition it is
cancelling a candidate list, not the dialog. Reuse the component's existing
IME guard (
useImeGuard) oruseDocumentImeLatchwhen the composing input can be anywhere inside the overlay; do not hand-roll a second latch.
Focus containment is a separate mechanism with a different scope: the Tab
trap tests DOM containment (container.contains(document.activeElement)), so it
reclaims focus from a sibling portal back into the dialog regardless of the
keyboard boundary. A sibling overlay's own Tab handling therefore has to expect
the trap to have run first.
Pinned by Modal.keyboardIsolation.test.tsx and
ProjectPicker.keyboardIsolation.test.tsx. Both open with a control that fires
the same chord where the boundary is known to work — every other assertion in
them is a negative, and a negative is worthless if the harness never delivered
the key.
All dangerouslySetInnerHTML content goes through DOMPurify, via
src/api/helpers.ts:
md(text)renders markdown-like formatting and sanitizes the result.sanitize(html)is the DOMPurify wrapper for already-built HTML.esc(text)escapes plain text (use this when you do not need markup at all).
A bypass is an XSS bug, so there is no "just this once" case.
The markdown renderer sets no dangerouslySetInnerHTML. Raw HTML in markdown
prose enters its tree only through rehype-raw. In the chain
MarkdownRenderer.tsx composes (rehypeBoundRawDepth, rehype-raw,
rehypeMarkFencedCode, rehypeUnwrapBlocks, rehypeSanitize, rehype-katex)
the two passes between rehype-raw and rehypeSanitize only mark and restructure
the tree; they add no attribute the sanitizer would not judge. Every pass that injects
elements of its own (the streaming effects, the redaction markers, the stable
root keys) is appended after sanitize. Two fences take other paths: a widget
renders in WidgetFrame's sandboxed iframe, and MermaidBlock inserts the SVG
mermaid drew under securityLevel: 'strict'. The allowlist and the verbatim pass
below live in components/markdown/sanitize.ts; the facade re-exports both, so a
second surface that admits raw HTML reuses the one policy instead of carrying a
copy. The allowlist admits aria-* and data-* attributes wholesale with one
exception: data-message-*, in any casing or dash spelling (the key is compared
with dashes stripped), is reserved for the transcript's own hooks and is dropped
from content before that allow.
The shared markdown pass remarkVerbatimUnknownTags preserves unknown single
tags as inert source text, including their case, bare attributes and quoted >
characters. Its single-tag recognizer scans each character with a fixed set of
attribute states; it must not backtrack over an entire raw HTML node. Malformed
block HTML reaches this check before the tag allowlist, so even an allowlisted
tag can carry an adversarial attribute sequence. This preserves the existing
permissive empty/unquoted-value handling without normalizing placeholders or
changing the separate sanitizer, executable-tag and multi-tag-block behavior.
react-markdown strips protocols it does not know. src/utils/urlTransform.ts
re-allows the editor deep links, vscode: and vscode-insiders:, and delegates
everything else to defaultUrlTransform. It also requires the URL to carry more
than the bare scheme, so vscode:// alone is not treated as a link.
Add a new protocol to ALLOWED_PROTOCOLS in that file, and only there. Each
addition widens what a model-authored or user-pasted link can launch on the host,
so treat it as a security change, not a formatting one.
In a desktop-app pane (isDesktopAppPane), MdAnchor opens an editor link
with window.open on a plain click, because the frame's CSP frame-src
refuses an in-place navigation to a custom scheme. Other pages keep in-place
navigation. In the desktop app that call reaches the window-open handler in
website/electron/external-scheme.js, which asks the user before opening it.
How a refused destination RENDERS is part of the contract (issue #9925): the
transform's rejection sentinel is '', and MdAnchor's !href guard renders
the label as inert text with no anchor — never <a href="">, whose empty
href resolves to the current page — matching md-notebook/Preview.tsx's
href ? <a …> : <span> trade. A test that pins an anchor existing for a
destination the transform rejects is pinning a defect.
One deliberate, key-scoped exception exists: a Windows absolute path
(WINDOWS_ABS_PATH_RE — a drive-letter path) is passed through for image
src only, because defaultUrlTransform parses C: as an unknown scheme and
would blank the sender's own uploaded image (issue #3497). The invariant that
makes it safe: ImgWithFallback (components/markdown/ImgWithFallback.tsx)
routes every local path to the same-origin /api/file-raw endpoint, so the raw
filesystem path never reaches the DOM, and
the shape (single letter + separator) cannot express javascript:/data:
payloads. Widening that regex or its key scope is a security change — the same
constant also decides which paths are treated as local file reads, so the two
decisions must stay on the one exported copy in urlTransform.ts.
A root-relative image (/images/a.png) inside a previewed file (a
BasePathCtx is set) is tried as an absolute path first, then against each
directory above the file, nearest first, up to eight levels
(siteRootImageCandidates). The leading / there usually names the root of the
repository or site the markdown belongs to — GitHub, Zenn and Docusaurus all
write images that way (issue #23623) — and nothing in the file says where that
root is. A same-named image in a nearer directory therefore wins over one at
the real root. Every candidate still goes through /api/file-raw, so the fallback
reads nothing the absolute path could not already ask for. When every candidate
fails, the broken-image fallback names and probes the path as written, as it
does for any other image, so its "no longer exists" wording speaks for that path
alone. That fallback states the failure through an inline ErrorNotice beside
a chip that copies the on-disk path. The notice offers no agent hand-off: the
renderer also previews unsaved drafts (the meeting note's Preview), and the
navigation would unmount one. Every surface that
provides BasePathCtx gets this (the file preview, the file explorer, the
meeting notes sidebar); outside them (chat, artifacts) a leading-slash path
stays absolute only.
To SHOW a gateway path's file name, use pathBasename (and
stripTrailingSeparators for a directory) from utils/pathBasename.ts, never
.split('/').pop(): a Windows gateway reports C:\repo\a.ts, which a /-only
split shows whole. The helper treats \ as a separator only in a drive-rooted
or backslash-UNC path, because on POSIX a backslash is a legal file-name
character. It is display-only and decides nothing about which paths may be read.
The dashboard can be built to live under a URL prefix (e.g. behind a reverse
proxy at /proxy/kirocrew/) with KIROCREW_BASE_PATH=/proxy/kirocrew npm run build; see Behind a reverse proxy at a sub-path.
The value is read once at build time and becomes Vite's base. src/lib/basePath.ts
exposes it as BASE_PATH ('' in the stock root build, so every helper is the
identity).
The transport shims (installBasePathShims) and DOM shims
(installBasePathDomShims) rebase fetch, WebSocket, EventSource and
URL-valued attributes automatically, so most call sites need no change. But a
dynamic import(), a window.location navigation, an AudioWorklet.addModule
load and a direct window.location.pathname read reach neither hook: wrap a
root-relative URL passed to those in withBase(), and read the app route with
appPathname() instead of window.location.pathname. basePath.test.ts
(call sites the shims cannot reach) scans the source and fails the build if an
unwrapped one slips in.
The memory editor, member recall, Memory V2 and Crew Manager memory surfaces are specified in memory, skills and hooks (Memory dashboard surfaces).
Always React Query (useQuery / useMutation) for server state. Do NOT use
manual useState + useEffect + useCallback for an API call. Prefer optimistic
updates through queryClient.setQueryData.
Query keys are arrays whose first element names the resource, kebab-case:
['mcp-servers'], ['agents-installed'], ['agent-detail', name]. Append the
parameters a fetch varies on, so a stale entry cannot serve a different subject.
Real-time updates arrive on a single WebSocket at /api/ws, read through
useWebSocket, which reconnects with capped exponential backoff (1s doubling to a
10s ceiling) and re-fetches state through Redux on reconnect instead of reloading
the page.
src/hooks/useWebSocket.ts is the composition point and the only import path:
it holds the frame routing table (one case per frame type), the silence
watchdog and the connect wiring, and it composes the owners in
src/hooks/websocket/. connection.ts owns the socket, its backoff and its
best-effort sends, and exposes the connection-scoped refs the open sequence and
the arms share; reconnectCatchUp.ts owns the first-connect and reconnect
sequences, in order, including their subscribe and focus frames;
streamBuffers.ts owns the per-frame coalescing of chat, reasoning, subagent
and sidebar-recency streams. Frame families live with their domain:
chatStream.ts and turnCompletion.ts (transcript frames, and what chat_done
means after its row), approvals.ts and composerCards.ts (coordinator
approvals; question, follow-up and folder cards), slotList.ts,
bundleReload.ts (the dashboard status frame), serverState.ts (the
server-owned caches), automationSeed.ts and voicePlayback.ts;
workflowRuns.ts reconciles the workflow rows those frames fold, attention.ts
owns the unread / read-relay rules and the focus senders, and browserEvents.ts
owns the window events that re-broadcast a frame. frames.ts decodes the
/api/ws envelope and types its FrameData for the router, and retiredIds.ts
holds the watermarked retired-id logs approvals.ts and composerCards.ts
share (and resolvedSince). sessionProjection.ts and slotProjection.ts apply
the session_projection and slot_projection frames to their caches,
contextTraceRefresh.ts decides when the Context tab re-reads its trace, and
rowDeliveryWatchdog.ts re-hydrates the active slot when a running turn stops
delivering rows over an open socket. The complete owner list is OWNER_MODULES
in src/test/useWebSocket.ownership.test.ts. The router's other arms are written
inline. A new
frame gets its case in the router; when it needs state an owner keeps, the arm
calls that owner (or reads a ref the owner exposes) rather than reaching into
it. An owner receives its dependencies (dispatch, queryClient, the socket
connection and peer owners) as arguments and never imports the facade; outside
src/hooks/websocket/ only the facade imports an owner, and owners import each
other only along the edges src/test/useWebSocket.ownership.test.ts lists.
src/types/index.ts is the one import path for the shared types it serves, most
of them the shapes of REST and /api/ws payloads. That file declares nothing. It
re-exports each owner below with an explicit export type { … } from list
(isolatedModules is on, so a plain export { … } of a type does not compile).
A new type for one of these areas goes to its owner and gets a line in that
owner's list; src/types/index.owners.test.tsx fails until it has one. No owner
imports the facade. An owner that needs another owner's type imports it with
import type from that owner and imports nothing else, and nothing outside the
family imports an owner. A module beside them in src/types/ that is not named
index.<area>.ts is not an owner and keeps its own import path.
Owner (src/types/) |
Holds |
|---|---|
index.gateway.ts |
the status push (StatusData), the update check, host metrics, session storage and its inventory, and each connected crew's version, capabilities, approval state and remote update |
index.jobs.ts |
scheduled jobs (CronJob), task-runner projects and their steps, dynamic-workflow runs |
index.capabilities.ts |
lessons and memory stores, skills and their budget, steering files, skill and MCP discovery, configured MCP servers and their scopes |
index.chat.ts |
the chat slot row (ChatSlot) with its turn identity and the chat_done payload, its todo list, MCP report and channel links; sidebar folders, tags and board lanes; transcript messages and the slot detail read; subagent and tool activity; content blocks; notifications and their channels; approvals; history session rows |
index.sources.ts |
pull requests, issues, the source provider id, an app repository's contributors |
index.artifacts.ts |
artifacts and their publication, publishing providers, forks, remote listings, session docs, folders, events, comments, web-app metadata |
index.sharedCrew.ts |
Shared Crew attribution: the browser-facing principal and its display snapshot, a session's creator, availability and trigger |
Redux Toolkit (src/store/index.ts) holds the cross-page shell state in four
slices:
| Slice | Owns |
|---|---|
dashboard |
SSE/WS connection state, chat slots, approval mode, optimistic slot add/remove, thunks for slot fetch and approval-mode change |
chat |
active slot, messages, session history with pagination, WS chunk/done handling, thunks for slot CRUD and history fetch/resume/delete |
notifications |
notification list with add/delete/clear plus their thunks |
instances |
the known Kiro Crew instances a user can switch between |
Server data belongs in React Query, not in a slice. Reach for Redux only when the state is shell-wide and not a cached server read.
A slice holding a collection the server re-broadcasts in full must merge the
incoming list into the one it already holds, never assign it. Assigning hands
every row a new object reference on every frame, so one row's change invalidates
every selector over the collection, every useMemo keyed on the array, and every
memoized child — and inside a Framer LayoutGroup it re-measures the entire list.
The symptom is a collection that visibly reloads when one member changed, which
reads as a bug rather than as an update. Broadcasts are coalesced server-side but
not suppressed (slots on a 200ms floor that stretches with the frame's size, up to
2s for a long list), so an active session delivers several full lists per second
and the effect is continuous rather than incidental.
What a merge has to hold:
- Membership and order come from the incoming list. The server stays authoritative on both; only per-row identity is carried across.
- Reuse a row only when it is structurally equal, so no consumer can read stale content off a kept reference.
- Leave the array itself alone when nothing moved. This is the half that pays: an equal-but-new array still reruns every downstream filter and sort.
- Compare field-agnostically and independently of key order. A comparator
that enumerates the type's fields stops seeing a newly added one and pins a
stale row — a correctness bug, where a redundant re-render is only a cost. A
serialization compare calls a locally patched row unequal forever, because an
in-place patch can append a key the server payload spells earlier. Use the
shared
jsonEqual(utils/structuralEqual.ts) rather than writing a second comparator — it already holds both properties, and a private copy is a second set of guarantees to keep in sync.
applySlots in dashboardSlice.ts is the reference implementation, driving both
authoritative writers (sseSlots and the fetchSlots refetch);
dashboardSlice.slotIdentity.test.ts pins the contract. Reusing an Immer draft
row inside a freshly assigned array is safe — a draft found in the assigned value
is finalized within the same scope, so an untouched row resolves back to its base
object and keeps its identity.
This is a convention for new and touched code, not a description of the current
store. One dashboard collection still assigns wholesale and is a known gap rather
than a counterexample: sseStatus replaces state.status as a whole object that
several panels subscribe to entirely. Converting it is worthwhile but is its own
change: its consumers need narrowing first, or the merge buys nothing.
Two habits belong to the same concern:
- Subscribe narrowly. A selector returning a whole map re-renders its
component on any write to any member; pass
shallowEqualwhen the component only reads members out of it, as the sidebar does forslotStatusDetail. - Don't re-rank a list on mid-turn activity. An ordering key should move on settled events only, or rows swap under the pointer while several sessions work.
- Framer Motion for orchestrated component transitions: enter/exit, layout animations, gesture-driven motion.
- Tailwind
transition-*for simple state changes (hover, toggle, color). - Tailwind
animate-*for simple indicators (spin, pulse) and the sharedanimate-rise/animate-scale-inentrances. - An always-visible indicator never runs an unbounded animation. An infinite
animate-pulse/animate-ping/animate-bounceon something that stays on screen keeps the browser producing frames on an idle dashboard. Bound it with the important longhand[animation-iteration-count:3]!(the!makes the bound win whatever order Tailwind emits the rules in) plusmotion-reduce:animate-none, or keep it static.src/test/idleAnimations.test.tspins the top-bar and rail indicators. - Do NOT add a new CSS
@keyframes. The existing ones in thesrc/styles/partials back specific low-level effects (skeleton pulse, caret blink, indeterminate progress); a new component animation goes through Framer Motion. - Hover PAINTS; it never moves or resizes. A hover state may change colour,
border, brightness or shadow, but not
scaleortranslate— growing a row under the cursor nudges its neighbours and reads as a layout change rather than "you are pointing at this". Press feedback (whileTap,active:scale-*) is fine: that answers an action the user took. A selected-state scale applied by STATE is an indicator, not a hover effect. A hover rotation is out of scope — it leaves the element's box where it is.- Removing a hover transform is only half the job: check the control still has SOME hover cue. On a small swatch or dot the scale is often the only one, and taking it away leaves a clickable thing that answers nothing.
- Pick the cue by what the element can actually show.
brightnessis a no-op on atransparentfill (tint the border instead), and a class-based cue cannot beat an inlinestyle, so an element whose colour is animated needs its cue on a property nothing animates. - A hover cue must not reuse a colour the control uses for its SELECTED
state — differ in colour, not merely strength. A dimmer shade of the
selected colour still reads as "selected" at a glance (a bright or accent
mark is selection-grammar whatever its exact lightness), so hover must paint
in a genuinely different colour, not a fainter one. The colour swatches show
this: selection speaks in
--text-strong(a near-white border) and--accent(a border orring-1 ring-accent), so their hover cue paints in a neutral--mutedoutline — which is neither, and the lightest neutral token with enough contrast on the darkest fill — and the memory-record card hovers toborder-border-strong, never its accent selected border. Where selection is an offset accent ring, the hover outline must also CLEAR it geometrically (outline-offset:-3pxinsets the line inside the fill) rather than sit at the ring's radius and mask it; do this structurally, not with an:not([aria-pressed])guard that silently misses a selected swatch marked by a conditional class alone. This is the same lesson as the left rail, where a full-strengthbg-bg-hoverread as selection and was fixed by weakening it to/60— applied to colour rather than strength. src/test/hoverNoScale.guard.test.tsenforces this and names the fix in its failure message. Deliberate exceptions live in that file's ALLOWLIST with a written reason.
Tailwind CSS 4, configured in CSS rather than a JavaScript config file. Two files own it:
-
src/tailwind-theme.css— the utility ↔ token bridge. Every--color-*,--radius-*,--shadow-*,--font-*and--animate-*theme key maps a utility (bg-accent,rounded-md,shadow-sm,font-mono,animate-rise) to the runtime design token of the same stem, sotext-muted/40renders a translucentvar(--muted). It also declares thedark:variant (@custom-variant dark ([data-theme="dark"] …), so dark mode follows thedata-themeattribute rather than the OS media query alone), leaveshover:at Tailwind's default@media (hover: hover)gate (a tap that reveals content makes iOS drop the click, so a hover-revealed control carries its own[@media(hover:none)]:visible state instead;src/test/hoverVariantPolicy.test.tsenforces it; content revealed from a JSonMouseEnteror focus handler follows the same rule throughhooks/useTouchReplay.ts: spread itspointerPropson the anchor and return early whilefromTouch()is true, asuseNavTip,useHoverIntent,RefLinkandMarkdownTocdo), and emits the iOS safe-area utilities (p-safe,top-safe-offset-*, …) as@utilityblocks. Adding a utility for a new token means adding one--color-<token>: var(--<token>)line here;scripts/check-phantom-classes.mjscompiles against this file to catch a utility whose token was never declared. -
src/index.css— the entry, read top to bottom in cascade order. First the Tailwind header: it imports Tailwind's theme and Preflight into their cascade layers, emits@tailwind utilitiesUNLAYERED (see the header comment there: the component CSS after it was written against v3's unlayered utilities and must keep competing with them on plain specificity), and lists the template sources with@source. Then the Preflight compensation, three v3 Preflight defaults restored as token-backed base rules (default border colourvar(--border), placeholder colourvar(--muted),cursor: pointeron enabled buttons). Then the imports offont-faces.css,design-tokens.cssandtheme-palettes.css; then the@layer baseelement defaults (box model, the global:focus-visiblering, the reduced-motion cut, the scroll-only scrollbar) and, unlayered, the ambient backdrop and the app-icon tints; then the imports of the other eight partials. Tailwind inlines each@importwhere it stands, so the import order IS the cascade order: never reorder the imports, and put a new rule in the partial that owns its surface. -
src/styles/*.css— the partialsindex.cssimports, listed here in import order. Each is one contiguous slice of the cascade, so some also hold a neighbouring rule that has no file of its own; those strays are named:font-faces.cssowns every@font-face: the script-fallback and straight-quote aliases, the brand faces and OpenDyslexic.design-tokens.cssowns the custom properties every theme shares and the default dark and light palette.theme-palettes.cssowns one[data-theme]block pair per named theme.chat-transcript.cssowns what a chat message paints and how it streams in. Strays: the composer's prompt-optimize overlay and approval glow, the update card's indeterminate progress bar,.animate-shimmer, the custom-font ligature toggle, the Kiro-theme overrides of nav, session-row and shell chrome, and the workspace-tree token mapping.scrollbars-and-touch-hit.cssowns the horizontal edge-fade mask for code and diff blocks and the 44px touch hit areas. Strays: the send-button sweep (.btn-sweep), the card hover glow (.card-glow) and the stat top-line accent (.stat-accent).shell-chrome.cssowns the top bar and its collapse ladder, the frameless Electron window chrome and focus mode. Stray:.scrollbar-none.focus-and-state-cues.cssowns the scroll-edge fades, the skeleton shimmer, the focus rings and the swatch hover cue. Strays: table striping, the follow-up chip width cap, the skill-load heading sizes and the highlight.js colours.sidebar-and-side-panel.cssowns session and folder rows, the list dock and the side-panel tab strip. Strays: the inline lucide icon size and the panel-icon pane morph.highlights-and-page-zoom.cssowns search, find and comment highlights and the coarse-pointer rules that stop page zoom. Strays: the artifact toolbar button heights and the mobile sessions-drawer width.liquid-glass.cssowns the glass material and every solid fallback (nobackdrop-filter, reduced transparency, more contrast). Strays: the settings icon-tile and goal-mark tokens, the dock pass-through and the global reduced-motion transition reset.content-fit.cssowns the rules that make content fit its box: font-metric compensation on the nav rail, the crew-chip cut edge, image and spacer reservations, the pane-dim token and the markdown-table breakout.
cli-mode.css,message-font-size.cssandcrew-notes.cssin the same directory are imported bymain.tsxinstead. A test that measures the stylesheet's source text reads it throughsrc/test/indexCssSource.ts(readIndexCss()), which splices every partial in at its import.
The build runs through @tailwindcss/vite; there is no PostCSS config. A
downstream edition's sources are added to the content scan by
editionExtensionPlugin in vite.config.ts, which swaps the
/* @kirocrew-edition-source */ marker in index.css for an @source line.
Utility names follow Tailwind v4: outline-hidden (not outline-none) is the
accessible outline suppressor, backdrop-blur-xs is the 4px blur, and the
shadcn/ui primitives animate through tw-animate-css.
Colors come from CSS custom properties defined in src/styles/design-tokens.css
and src/styles/theme-palettes.css, including the
semantic roles --aim, --clarify, and the --diff-* family. Never a hardcoded
#hex / rgb() / rgba() literal, and never a raw palette class
(text-green-500, bg-amber-400): state colors are text-ok / text-warn /
text-danger / text-info, and a running state is text-accent. See
theming-contract for the variable set, the stable class
hooks, and the checkers.
No scrollbar is visible at rest, anywhere in the dashboard
(decision).
A scroll box either hides its scrollbar entirely (scrollbar-none: the sidebar
lanes, the nav rail, the tab strips) or shows a thin thumb only while it is being
scrolled, in a column it reserves anyway so the reveal moves no content. The
second form is the default and needs no class: the base layer in index.css
keeps the 6px WebKit column with a transparent thumb and paints it under
[data-scrolling], which lib/scrollReveal.ts sets on the scrolling element
and clears after a short linger (Firefox takes the same two states through
scrollbar-width: thin and scrollbar-color, fenced behind the -moz-appearance
probe because Blink drops the pseudo-elements once those are set). Never add a
::-webkit-scrollbar-thumb colour or a scrollbar-color whose selector lacks
[data-scrolling], never scrollbar-width: auto, and never a hover-revealed
thumb: the pointer rests over the chat transcript most of the time, so hover is
"at rest" there. The global rule and the document scroll listener both stop at a
shadow boundary; Pierre's code, diff and tree surfaces are reached through
unsafeCSS keyed on the same attribute (PIERRE_SCROLL_REVEAL_CSS, folded into
both option factories in src/pierre/config.ts, and the tree's
PIERRE_TREE_STATE_ROW_CSS), and scrollReveal attaches to those hosts' shadow
roots itself (SHADOW_SCROLL_HOSTS). When a box's edge does not make it obvious
that it scrolls, the cue is an edge-fade mask (.edge-fade-x, useScrollEdges)
or a "more below" affordance (MORE_BELOW_MASK, JumpToBottomButton), never a
resting thumb. src/test/scrollbarRevealOnly.test.ts scans src/ for every
shape that paints one at rest and measures the revealed thumb's contrast per
theme; the no-scrollbar-at-rest rule in AUTOSDE.yaml blocks it in review.
Three of those rules are enforced by @shadcn/lint inside the blocking
eslint src/ --max-warnings 0 gate (configured in eslint.config.js, the
shadcn block):
shadcn/no-raw-colors— a palette class or a literal SVGfill/strokewhere a token belongs. Use the token; a logo whose colors are the artwork's own gets a file-level override (seeKiroGhost.tsx).shadcn/no-unknown-classes— a class Tailwind emits no CSS for. Usually a typo, a v3 spelling (outline-none,resize-vertical), or a class whose stylesheet was deleted. A class that IS real but lives outside the theme's import graph — an app stylesheet authored as a TS template string, a selector hook a Playwright spec locates by — is listed in the rule'sallowwith the file that owns it; the entry allows a name, it generates no CSS.shadcn/require-static-classes— aclassNameon aui/primitive built from a value the linter cannot read (an imported constant, a function call, an arrayjoin). Keep the class strings in the file that applies them: a shared class string becomes a small wrapper component (FilterMenuLabel), a helper call gets acn(...).
The same gate refuses browser-native dialogs: confirm, alert and prompt,
bare or as window.*, are errors through no-restricted-globals and
no-restricted-properties. Use useConfirm() / ConfirmDialog or an in-app
notice instead. A file allowlist holds the standing inventory and only shrinks:
delete a path when its last native dialog is gone, never add one. Tests
(*.test.{ts,tsx}, src/test/) are exempt.
shadcn/no-restyle — a className that changes what a ui/ primitive owns
(its color, spacing, shape, typography) — is off in that gate: a few hundred
call sites restyle primitives today and the gate is a hard zero, so turning it
on is a design decision (fix the sites or write per-component contracts), not a
lint toggle. What IS enforced is that the backlog cannot grow.
scripts/check-restyle-ratchet.mjs (npm run lint:restyle-ratchet, run by
CI beside the phantom-classes gate) lints with the rule through its own config
(allow: ['layout'], so margins and widths pass) and holds every file at the
count recorded in scripts/restyle-baseline.json: a file whose count rises, or
a file with findings and no entry, fails the build; a file whose count fell
fails too, until you record the drop with
npm run lint:restyle-ratchet -- --update-baseline, which only ever lowers a
number or prunes an entry that reached 0 — so progress is locked in, not left
to a log line. Lowering a count is the only edit the script makes; the one hand
edit is moving an entry to a file's new path when the file moves (the count may
not grow). It is a separate script rather than ESLint's bulk suppressions
because editors lint through the Node API, which ignores the suppressions
file, and the CLI loads that file for every config, which would fail the i18n
eslint run on "unused" entries. Adding a restyle to a file at its
ceiling means using the primitive's own variant or size prop, keeping layout
classes at the call site, or wrapping the primitive in a small named component
that carries the class in the component file — not raising the number.
no-inline-styles and no-arbitrary-values stay off by design — inline
style={} is the mandated method for apps, and translucent theme surfaces are
bg-[color-mix(…)] because the color tokens carry no alpha channel.
Built-in themes are picked in Settings, Display tab, and the choice syncs across
instances. Each theme has a dark and a light block, and the default theme's
data-theme is the bare dark / light rather than a prefixed slug.
Shared CSS utilities: .top-bar-pill and .topbar-glass
(src/styles/shell-chrome.css), .scroll-shadow, .table-striped, .skeleton
and .focus-ring (src/styles/focus-and-state-cues.css). A theme change
crossfades through a transition on body (src/index.css).
All old/new source pairs render through PierreFilePair in src/pierre/index.tsx.
That wrapper owns a layout-independent renderer-thread budget before the lazy
Pierre chunk loads, because Pierre constructs the raw diff synchronously before
its worker pool or row virtualizer participates. Inputs outside the budget keep
both complete files, header controls, native selection, wrapping, and theme
styling in a bounded plain side-by-side or sequential surface. A translated
status identifies the simplified view; it omits syntax colour and hunk
interleaving by default, and a "Show line-by-line diff" control in a strip
between the header and the scroller opts one pair into the real diff: the
computation runs in a Web Worker (src/pierre/diffOffThread.ts), so the
renderer never blocks, and the result renders through the hunk-based patch
path with unchanged ranges folded. The content limit is measured in JavaScript UTF-16
code units rather than encoded bytes so the guard stays allocation-free while an
editor changes. Editable live diffs use the same
predicate and degrade to the ordinary editable file surface rather than becoming
read-only. Do not duplicate or weaken the limits at call sites.
Body is 14px (0.875rem, set on body). Descriptions and details use
text-sm (14px); labels, buttons and sidebar entries use text-[13px]; badges
and captions use text-[12px]; decorative icons text-[10px] to text-[11px].
Code blocks are 13px mono.
Minimum readable text is 11px, and nothing goes below 10px. Do not use
text-xs (use text-[13px]), and do not use text-[9px] or smaller.
A builtin app does not need a NAV_ITEMS entry, and App.tsx does not need a
route for it. BuiltinAppRoute resolves the catch-all /:builtinApp against the
registry in src/apps/builtinRegistry.ts.
To add one:
- Create the page component under
src/apps/<name>/(orsrc/pages/). - Export it as the module default.
- Add one entry to
BUILTIN_COMPONENT_REGISTRY(aBuiltinAppEntry):'/my-app': { component: lazy(() => import('./my-app/MyAppPage')), appId: '<app.json name>' }.appIdmust equal thenamein the app'sapp.jsonmanifest. A page that opens an absolute path handed to it in its URL also setsopensPathParamto the query parameter it reads (<route>?<param>=<path>). The file viewer's ⋯ menu then offers "Open in " for it throughsrc/apps/pathOpener.ts, which names no app: it takes the first such entry whose app is enabled and routed natively. - Declare
ui.pagesin the app'sapp.jsonmanifest, and itsui.iconname. - If the icon is not already in
src/apps/builtinIcons.tsx, add it toBUILTIN_ICON_REGISTRY(Lucide element,size={16}).
Components are lazy so a builtin app does not weigh on the initial bundle. The
route must be a single plain top-level path segment: the registry is matched
against location.pathname only, so a multi-segment, query, or hash route would
register and then never resolve. The same constraint and the reasoning behind it
are in extension-seams, which covers registering routes and
icons from a downstream edition instead of editing the seed maps.
The Crew editor's Capabilities pane and its draft, preview and save contract are specified in crew mode (Crew capability drafts).
Switching to a remote Crew hides the local dashboard without unmounting it, so
a floating layer must not portal straight to document.body (lint refuses
createPortal(…, document.body) and Radix imports outside components/ui/).
src/components/overlayRoot.tsx is the reference; in short:
- Portal through
<OverlayPortal>oruseOverlayRoot(). Inside the local pane that resolves to a body-level container hidden with the pane; anywhere else it isdocument.body. - A switch counts as a click outside for layers that hold no input: the shared
Radix menus, context menus and selects close (
useCloseWhenCrewHidden). A new shared Radix wrapper passescontainer={useOverlayRoot()}insideMountAfterCommit, then either closes the same way or, if it can hold input, stays mounted and refuses dismissal while hidden (standDownWhileHidden, as popovers do). A popover is modal only inside a Radix dialog. - Every other layer stays mounted and hidden, and hiding stops painting, not
listening. Required: every document- or window-level key handler of a layer
rendered under
<OverlayPortal>that commits, discards or claims a key readsuseLocalCrewHidden()and stands down while it is true (asModal,useDialogFocusTrap,useListKeyboardNavanduseMenuKeyboarddo).src/test/overlayKeyGuard.inventory.test.tslists every such listener and fails on a new one until it is guarded or exempted with a reason. - A Radix dialog and what it opens stay on
document.bodyacross a switch (GlobalOverlayScope), as does the notification banner.