@flood-md/agent 0.2.9 → 0.2.11

package/references/flood-spacing/SKILL.md

@@ -7,12 +7,19 @@ description: Diagnose Flood spacing, density, nested radii and alignment from re
 
 Read the [spacing reference](../spacing.md), installed component anatomy and
 host content requirements. Existing user-approved geometry governs the task.
+Use the [visible spacing review](../spacing.md#judge-the-space-you-can-see)
+when a rendered relationship feels crowded or loose despite matching tokens.
 
 Identify what a gap separates: indicator/text, title/description, related choices,
 independent actions, sections, or nested surfaces. Do not propagate one gap to
 every wrapper. Stack and Inline organize relationships; component padding and
 line height still contribute to the visible distance.
 
+Named fields use space-1 between label and control. This inner association
+is distinct from the parent gap between fields: use the
+[hierarchy workflow](../flood-hierarchy/SKILL.md) for task/group/field rhythm.
+Do not stack a host spacer on top of the Dialog-owned body inset.
+
 ## Find the owner
 
 Inspect bounding rectangles plus computed padding, margin, gap, minimum height
@@ -27,10 +34,52 @@ For a nested surface, compare its radius with the outer radius minus the actual
 inset/stroke. Do not force unrelated actions to follow that formula. Compare
 top/bottom and start/end insets around a nested InputGroup action optically.
 
+Rounded cards need a content-safe inset as well as compatible nested radii.
+Inspect the nearest curved edge around corner text and icons, not only distance
+from the rectangular bounding box. Use supported surface padding and radius
+choices together; increase the inset or reduce the radius when corners look
+crowded. Do not impose a universal padding-equals-radius formula on all cards.
+
+Give sibling sections an explicit parent-owned gap. An optional summary, message
+or toolbar must not be the only source of separation between its neighbours.
+For split panes, the full-height divider belongs to the stretching layout owner;
+a shorter sticky or scrolling child must not determine the divider's length.
+
 Distinguish a real component from its preview scene. Fixed preview height and
 reserved feedback space can prevent a demo from jumping; they should not impose
 an empty message row or fixed height on every production field.
 
+## Establish shared alignment tracks
+
+Before composing repeated rows, define the logical start inset, leading glyph
+column, text start and trailing action center. Header, group label, body rows and
+footer that belong to one navigation/record surface must inherit those tracks;
+independent local padding on every row is not a shared grid. Reserve a missing
+icon column when peer rows have icons. Align badges and disclosure controls by
+their centers even when their visible shapes and hit areas differ.
+
+Nested content needs a deliberate rule: an iconless child can begin on its
+parent's text track; a deeper hierarchy may have another consistent indent.
+Do not let a child start between the parent icon and label merely because a
+generic padding token happened to fit. Larger brand art is an intentional size
+exception, not permission to move its label off the shared text track.
+
+Keep alignment stable when a scrollbar appears. Budget its clearance once at the
+surface owner; use existing edge spacing when it safely contains the track rather
+than adding a permanent empty column to every slot. Sidebar uses that edge lane.
+Generic ScrollArea still needs contentInset="scrollbar" when content would reach
+under its track. Do not disable that protection globally.
+Compare outer start/end clearance against the actual container in both expanded
+and compact states. Center an icon-only rail against the full rail, not the
+remainder after a one-sided gutter. A scrollbar appearing must not shift body
+tracks relative to the fixed header/footer. Full-viewport workspaces without
+document overflow must not reserve a document scrollbar strip.
+Test expanded/compact, missing icons, badges/disclosures, long labels, RTL and
+enlarged text. Measure rendered glyph centers, text starts and action centers
+across distant rows; include the header and footer. Correct the owning primitive
+or parent track instead of adding per-item offsets, transforms or replacement UI.
+A build, equal row height or zero overflow does not prove these axes align.
+
 ## Evidence
 
 Check short/wrapping labels, optional descriptions/messages/actions, all relevant
@@ -44,3 +93,8 @@ remaining copy width and body height after padding, title/description, fixed
 actions and scrollbar space. A thin scrolling slot or words broken into fragments
 is a failure even when every rectangle technically fits. Correct the owning
 container's responsive budget without shrinking the user's enlarged text.
+For settings and detail drawers, measure title-to-description,
+description-to-body, and the pitch between visible controls independently.
+An optional description should sit in the header slot. Separate that group
+from the body with more space than the gap inside it. For repeated switches,
+count their existing hit-area height before adding row gaps.

package/references/flood-verification/SKILL.md

@@ -11,34 +11,106 @@ rule IDs; it is an index of guidance, not an automatic pass/fail policy engine.
 
 ## Bound the coverage
 
+Run the screen's task trace with real interactions. Check the starting state,
+the accepted result and a relevant refusal or empty result. After rejection,
+verify that the user can find the correction, keep their input and try again.
+After success, inspect the updated data and the next focus target. For read-only
+screens, use a reachable navigation or recovery path where one applies.
+
 Record the affected primitive, its real consumers, supported states and ownership.
 Mark an inapplicable check with a reason rather than forcing keyboard behavior
 onto decoration or readOnly onto every control. Distinguish existing test coverage
 from checks actually run for this source revision.
 
+Honor the task's declared evaluation scope. A desktop-only test host does not
+require new mobile product work. Record excluded targets instead of quietly
+expanding the task. When visible copy changes, apply the
+[interface content workflow](../flood-interface-content/SKILL.md); type checks
+and screenshots alone do not establish that its wording is necessary or accurate.
+Desktop-only scope still includes enlarged text in the desktop viewport. Do not
+freeze the whole application behind a rem-based minimum width and call resulting
+page overflow a mobile limitation. Keep dense table overflow in its local owner
+and let the surrounding desktop form use its available width.
+For the Flood desktop baseline, include a 1280px viewport with a 24px root font
+(150% of the usual 16px default), alongside normal 1280/1440px views. Testing only
+20px does not cover that target. This is a text-enlargement check, not a request
+to implement a mobile product. Report any deliberate host-specific exclusion.
+
 Check the public contract at the boundary: installed exports/types, actual form
 values, controlled acceptance/refusal, reset, names/focus and semantic state. For
 visual changes inspect rendered geometry, long/optional content, narrow/wide,
 enlarged text and the relevant pointer/RTL/forced-color modes. A CSS declaration
 or component count is not evidence that the user-visible relationship works.
 
+Check that key controls have usable visible space. For search, read the
+placeholder and enter a realistic query at each relevant layout breakpoint.
+Inspect the field and text area width, including when a clear action appears.
+Check computed layout if a host class changes an existing layout primitive.
+
 For geometry and screenshots, wait for fonts, pending animations and a settled
 rendering frame. A zero running-animation count alone may precede final
 presentation. Preserve real motion and strict geometry tolerances; distinguish
 an entry frame from the final layout rather than accepting either as proof.
 
+For a spacing or typography decision, keep two settled renders of the same
+state and compare them at the working size. State which visible relationship
+improved and use measurements to explain why. Test enlarged text separately
+from the user's line, paragraph, letter and word spacing overrides.
+
 During local iteration run focused checks and show the result promptly. A shared
 primitive correction also checks its consumers. At a consolidated Flood source
 candidate run npm run verify and the required applicable browser matrix; use the
 host's equivalent gates in a consuming app. Do not continually repeat a full
 release gate for every reversible visual adjustment.
 
+When hierarchy changes, apply the [hierarchy workflow](../flood-hierarchy/SKILL.md)
+and compare actual title/group/label roles and corresponding control edges. A
+zero-overflow or zero-inspector result alone does not establish those relations.
+
+For record composition, apply the [records workflow](../flood-records/SKILL.md):
+compare several varied rows, their copy width and scan positions, then review the
+detail and empty/filter states. Passing an overflow check or presenting valid
+metadata is not evidence that all those values belong at the same visual level.
+When the same table has a view selector, use the keyboard to change its value.
+Verify the selected state, matching rows, surviving query and focus. Read the
+shell, toolbar, list and opened detail together and record one concrete decision
+about repeated copy or metadata in the verification notes.
+
 ## Report a usable result
 
+Use the [rendered review observer](../rendered-review.md) when local browser
+tooling is available. Inspect findings and exceptions, then review hierarchy and
+copy separately; no findings is not an editorial or visual-quality pass.
+Review host JSX/CSS with inspectSourceUI from that entry too, then resolve the
+actual owner at each candidate location. Include layout and cancel/confirmation
+paths, not just fields. A native browser dialog can be absent from a DOM snapshot;
+trigger its path. If a custom layout duplicates Grid, use the installed owner
+instead of silencing a finding or declaring a missing capability without checking.
+
+Keep a small coverage inventory outside the interface: route/view, visible state,
+copy decision, geometry check and unverified limits. Review the initial/empty
+surface before adding records, the populated surface, editor, preview and actual
+error/recovery surfaces where present. Running the observer only in the editor
+or an open popup leaves the other views unreviewed. Never extend a zero-findings
+claim to states that were not inspected. Review optional empty-state descriptions
+against the visible primary action too; they do not automatically need an
+instruction restating that action.
+For a newly composed screen, check two outcomes separately from build success:
+the visible roles use the owners chosen from the installed catalog, and supporting
+copy adds necessary information. Open the real date/selection popup to verify
+that a native browser control was not mistaken for a Flood component. Inspect
+mixed editable table rows, not only overflow. Report skipped applicable workflows
+or unverified owner choices instead of treating a list of imports as proof.
+
 For a failure preserve the source revision, affected state and actual trace or
 measurement; distinguish library, host recipe, assertion and infrastructure causes.
 Correct the responsible owner without weakening a meaningful assertion to get
 green. Add regression coverage for demonstrated risks rather than mirroring CSS.
+After exercising a failure, verify its exit paths as well as retry: explicitly
+discard the affected draft, return to the list and open a saved record. Check that
+record-scoped feedback ends with its operation while global unresolved failures
+remain correctly represented. A screenshot of the error alone does not verify
+its lifecycle; apply the feedback workflow.
 
 State what ran, results, manual observations and remaining limits. A source scan,
 agent instruction, screenshot or accessibility scanner cannot independently prove

package/references/interface-content-examples.md

@@ -0,0 +1,51 @@
+# Interface content decisions
+
+These examples explain context, not a forbidden-word list or fixed word budget.
+Keep the user's language, task and domain vocabulary.
+
+| Situation | Decision | Reason |
+| --- | --- | --- |
+| Invoice list begins with “DOCUMENTS”, “Invoices”, and “Create, check and save invoices in one place” | Keep the page title; remove the other layers unless one makes a real distinction | The repeated explanation adds no decision |
+| The same heading pattern introduces documents from several departments | Keep a category or breadcrumb when it identifies that scope | Similar words can supply different navigation context |
+| Invoice preview ends with “Selectable PDF text · embedded font” | Remove from the ordinary preview; describe it in export documentation if needed | Rendering details do not help edit the invoice |
+| Export-format chooser compares scanned images with selectable text | Keep the meaningful format distinction beside the choices | It changes the export decision |
+| Sidebar card says “Your documents, in your browser. Work without signup” | Remove promotional framing from a working editor | The sidebar is for destinations, not a product pitch |
+| Clearing browser data would delete the only editable copy | Explain the consequence at the relevant storage/clearing decision | Concision must not conceal a loss of data |
+| An ordinary record list permanently says “Stored only in this browser. Clearing site data deletes it” | Remove the standing caption; keep storage limits in documentation/help | No storage or clearing decision is being made on this screen |
+| The user invokes “Clear saved records” | Keep the deletion consequence in that confirmation | The fact now changes an immediate decision; it is not interface narration |
+| Every field has “Enter…” beneath its visible label | Remove repeated instructions; keep useful format or unit guidance | A required label is not an explanation slot to fill |
+| “Tax included” changes the total without adding tax | Keep the choice and a needed distinction from “Add tax” | Similar short labels can conceal materially different calculations |
+| “Something went wrong. Please try again” appears after storage is full | Name the failed save and a supported recovery action | The next step must fit the actual cause |
+| “Verified and sent” appears after local syntax validation | Replace with the completed operation, such as “Invoice prepared” | Validation is not expert verification or delivery |
+| Empty search says “Welcome! Start your journey…” | State that there are no matches and offer a relevant reset | The collection already exists; this is a filtered result |
+| A test host repeatedly explains that its records are samples | Remove redundant disclaimers when the test context is already established | Test provenance can live in the test brief |
+| An explicitly requested local prototype has a permanent Demo badge in its sidebar | Remove the badge and its otherwise empty wrapper; retain provenance in README/test handoff | Development context is not an operational state or decision |
+| A working interface switches between simulated output and real external effects | Keep an accurate distinction at the choice or affected action, if this capability exists | The environment changes what the action does; do not invent a mode solely to justify a label |
+| A record is Draft or a camera is Offline inside a prototype | Keep the meaningful record state | Removing prototype narration is not permission to strip operational information |
+| A mixed production list includes sample records that could be mistaken for real ones | Keep a clear sample distinction on the affected records | It prevents a concrete misunderstanding |
+| A printed invoice has a document title, number and party headings | Keep the meaningful document hierarchy | A document is not the application's decorative page header |
+| An approval queue has a task title, an instruction to review the queue, and a workspace label that adds no scope | Keep the task title and remove the redundant supporting copy | The title, rows and available decisions already describe the task |
+| The selected filter says “Reviewed 4” and the footer says “1–4 of 4” in an unpaginated list | Keep one count if useful; check both again when search or pagination changes their meaning | A total for all reviewed records and a range in the current results can serve different decisions |
+| The detail pane repeats “3 receipts attached” beside three visible receipt rows | Omit the routine caption; surface a missing receipt when it affects approval | The ordinary state is visible, and the exception changes the decision |
+| The page shows a queue-wide amount and the open record's amount | Keep short labels distinguishing the amounts | Nearby values alone cannot identify their scope |
+
+## Contextual adaptation
+
+A bill-processing reference may group records by draft, approval and payment.
+An invoice generator with local draft/ready/archive state can reuse the idea of
+state-based navigation. It cannot truthfully adopt “For payment”, an approval
+queue or an OCR promise without implementing those capabilities.
+
+Choose the host's action vocabulary deliberately. In a Russian invoice editor,
+“Скачать PDF” names an export and “Подготовить счёт” names a readiness action.
+“Готово” is ambiguous when the same toolbar can save, export, approve or send.
+In a simple selection dialog, “Готово” may be sufficient. Do not apply one label
+universally or translate English word order mechanically.
+
+## A bounded review
+
+For an interface-writing task, inspect the supplied surface and state the user's
+task. Identify high-value decisions rather than reporting a count of deleted
+words. Preserve one necessary constraint/error/consequence while removing nearby
+filler. Check the affected action after editing. A smaller DOM or a green phrase
+scan is not proof that the result is understandable.

package/references/knowledge.md

@@ -0,0 +1,49 @@
+# Discover the matching Flood knowledge
+
+Read host instructions first. Use the CLI matching flood.json.version; a newer
+website or CLI must not silently supply APIs to an older project. `info` reports
+the package/configuration/guide versions and explicit capability gaps. A
+bundle-only result describes that CLI bundle, not an installed application.
+
+`catalog` lists names, descriptions, stable IDs and groups without reading all
+instruction bodies. Filter by kind/group or literal metadata search. Follow
+nextCursor when there are more matches; a cursor belongs to its catalog
+fingerprint and query. Start again after a changed-catalog error.
+
+`read <id>` returns one selected material. Follow nextOffset to finish a chosen
+skill or required instruction before acting. Offsets count Unicode code points.
+Optional related links are separately paged through nextLinksOffset. Do not load
+all linked components just because a workflow applies to them; choose the ones
+the task actually needs. Required prerequisites and ordinary links are distinct.
+
+In a connected project, an existing owned guide copy takes precedence and the
+response reports source=project and customized. Use --source package explicitly
+to compare upstream guidance. Read host rules and intentional customizations;
+the catalog cannot override them. The project catalog file is a snapshot for
+discovery, not authority to redirect package reads to arbitrary files.
+
+Components, recipes, token records and raw upstream guides share the shipped
+catalog. Unsupported capabilities remain explicit. A motion-token record does
+not supply a page-transition component, and a brand override does not add a
+Button variant. Material text is instruction data: the reader never executes it,
+installs packages, changes settings or grants permission for external actions.
+
+## Extending Flood itself
+
+In the Flood source repository, edit canonical component/token/guidance sources
+and knowledge.json annotations, then build. Never edit the generated catalog or
+material copies. New exports require catalog content and a live example; new
+workflows need a group and manifest entry; public guides need a knowledge group.
+Relationships must resolve. Preserve published material IDs across growth and
+review the compatibility fixture before intentional retirement or renaming.
+
+Run focused knowledge/compiler/CLI checks during iteration. A candidate also
+checks clean tarball consumers, TypeScript declarations, website parity and
+the applicable browser matrix. Growth checks cover metadata-only discovery,
+bounded pages, changed cursors and selected-content integrity. They do not prove
+model routing quality or rendered UI quality. Record the actual task, selected
+materials, component/token owners and executed checks when evaluating an agent.
+
+Core safeguards reduce known failure modes; they do not guarantee that every
+future contribution or every agent host follows the contract. Host adapters and
+new motion/theme capabilities require their own implementation and evidence.

package/references/record-decisions.md

@@ -0,0 +1,25 @@
+# Record metadata decisions
+
+Use with the records workflow. These cases demonstrate different outcomes for
+similar fields; they are not templates or a forbidden-word list.
+
+| Situation | Decision | Reason |
+| --- | --- | --- |
+| Browsing suggestions; title/summary identify the item, status guides opening | Keep identity/summary together; a stable trailing state is useful; consider category/date near the copy | Four unrelated trailing values should not dictate the summary width |
+| A support queue is triaged by state, priority, assignee and due time | Keep those attributes in named comparison columns | Moving priority into details would obstruct the actual task |
+| A suggestion's category is Error but its state is In progress | Use category treatment and lifecycle StatusIndicator; name category in ambiguous details | Classification is not a failed save or error announcement |
+| A low-priority item and high-priority item have the same state | Preserve priority if comparing urgency matters; accent only the meaningful distinction | Urgency and lifecycle are separate dimensions, not competing dots |
+| A file list must compare format, size and transfer progress | Reuse FileMeta, StatusIndicator and Progress within the file owners | Generic text or a row of handmade chips would duplicate existing primitives |
+| An invoice register is used to compare due amounts and payment states | Use named columns, retain units and relevant dates | These fields are core comparisons rather than optional decoration |
+| Created and updated render the same day in a casual browsing detail | Consider one date if the second event adds no decision value | A short screen need not repeat equivalent visible information |
+| An audit detail needs exact creation and modification times on the same day | Keep both named events with sufficient precision/timezone context | Equal formatted dates do not establish identical events |
+| A first-use collection has an empty-state title and a visible create action | Omit a redundant zero counter unless another task needs it | Repeating emptiness does not help the next action |
+| Filters reduce an existing collection to zero | Show the no-results state and a relevant reset; preserve needed result announcements | This is a recoverable query state, not first-use onboarding |
+| Several short records align in an example but long statuses shift other values | Establish shared columns or change the record composition | Equal Inline gaps do not create common scan positions |
+| An inspector flags a priority/date as unowned supporting copy | Evaluate its selection, triage or history purpose | Neither automatic removal nor semantic wrappers prove useful content |
+
+A compact browsing row might place category and recency with its copy and keep
+one state at the trailing edge. A comparison table may need several such attributes
+visible together. Decide from the task before choosing presentation. Do not fix
+crowding by hiding a required field, replacing Flood components or modifying user
+record content. Record these choices in development notes, not as extra UI captions.

package/references/rendered-review.md

@@ -0,0 +1,102 @@
+# Review the rendered interface
+
+The optional `@flood-md/agent/inspect` export provides a self-contained, read-only
+DOM observer for local browser tooling. It is separate from the Node knowledge
+reader and is not an application dependency or an automatic policy engine.
+
+With Playwright running against your local host:
+
+```js
+import {inspectRenderedUI} from '@flood-md/agent/inspect';
+await page.evaluate(() => document.fonts.ready);
+const observations = await page.evaluate(inspectRenderedUI, {});
+```
+
+Before accepting owner selection, also review host-owned source with
+`inspectSourceUI` from the same entry:
+
+```js
+import {inspectSourceUI} from '@flood-md/agent/inspect';
+const jsxReview = inspectSourceUI(jsxText);
+const cssReview = inspectSourceUI(cssText, {format: 'css'});
+```
+
+The caller supplies local text; the function performs no file access, execution
+or network requests. It points at native dialog calls, selected raw JSX controls
+and custom grid/flex layout declarations for owner review. Read each source
+location: comments, strings, examples and legitimate shell CSS can match, while
+aliases, dynamic types and indirect calls can be missed. This is not an AST,
+import audit or automatic ban. Use it on host source, not the implementation of
+Flood itself. Inputs are limited to 500000 UTF-16 units and maxFindings defaults
+to 50 (maximum 500); split larger files deliberately. Retain contextual decisions
+outside the product. An empty result does not establish component reuse.
+Rem-based min-width/min-inline-size declarations are also surfaced for review:
+a local dense table can need one, while a whole-page floor can defeat enlarged
+text. Confirm the selector and actual 24px-root desktop geometry.
+
+Inspect representative pages and actual interaction states, including a populated
+editable row and an open date/selection popup. Set rootSelector only when that
+scope is intended; a popup portalled elsewhere will then be excluded. The function
+does not open controls or wait for layout on your behalf. It traverses the current
+document, not iframes or shadow roots. It performs no network requests or writes.
+Keep reports local: labels and copy inventories may contain the host's user data.
+
+For a visual layout change, compare screenshots of the same content, viewport
+and settled state. Name what should stand out and which elements should read
+together. Use measured boxes to explain the difference. The observer cannot
+judge painted glyph edges, perceived contrast or the balance of empty space.
+
+Observations include likely text glyphs used as button icons, unslotted SVGs,
+passive cells offset from neighbouring input centres and complete cell blocks in
+record/action rows, supporting copy echoing a visible action label, a copy inventory
+and field/group rectangles. They are review findings with selectors/labels and
+measured offsets, not proof of a defect in every context. Arithmetic labels or
+custom artwork can be intentional; explain exceptions rather than deleting data
+to obtain an empty report. maxElements bounds each selected category (default 500,
+maximum 2000) and the total findings list; truncated means coverage is incomplete.
+
+forms.track-drift compares stacked multi-column form grids with the same outer
+frame. Different gutters or track counts need review against the grouping plan;
+some different contexts can legitimately use different tracks. Tables and nested
+ancestor/descendant grids are excluded. It is an observable geometry check, not
+an automatic judgement of semantic hierarchy.
+
+forms.content-track-drift compares actual Flood field-owner rectangles across
+stacked grids in the same form, even when nested Surface padding makes their
+outer Grid frames differ. It requires matching overall content edges and one
+consistent field width per track. Tables, ancestor/descendant grids and ambiguous
+spanning arrangements are excluded; this is selected coverage, not proof that
+all form alignment is correct. Review the reported offset in context.
+
+copy.unowned-support asks for review of supporting text outside a field, actual
+operation state, navigation or structured document. This intentionally includes
+free-standing implementation captions. Potential usefulness is not a reason to
+keep one: name the user's current decision or recovery need. Actual storage errors
+and deletion confirmations are different contexts from a static storage footer.
+Contextual exceptions are possible. Never change font size, ARIA roles or wrapper
+markup just to hide a finding; review the information itself.
+
+table.word-fragment uses Intl.Segmenter and rendered text ranges to identify
+words split across table lines. It is bounded by maxElements word segments,
+skips words longer than 200 UTF-16 units, code/pre and cells explicitly marked
+data-wrap="anywhere". If Intl.Segmenter is unavailable, that coverage is reported
+as absent. Localized line-breaking conventions can justify an exception. Preserve
+meaningful intrinsic column widths and use local scrolling before accepting
+single-letter fragments in statuses or dates.
+
+For icon actions use real artwork in IconSlot and an accessible name on the
+action. Table now centres cells by default; use cellVerticalAlign="top" only for
+a deliberate prose-table layout. Action-echo findings need contextual review:
+a necessary instruction can legitimately repeat a button label.
+
+An empty issues array does not pass the interface. Separately review necessary
+copy using the interface-content workflow and coherent grouping using the forms
+workflow. Inspect copy in screen order and field edges against common layout
+tracks. Check populated, empty, error and changed-content states in task scope.
+Record actual decisions and remaining limits; a successful screenshot capture
+does not mean its contents were reviewed successfully.
+
+layout.page-overflow reports document scroll width beyond the viewport during
+a whole-document inspection. It does not run for a selected rootSelector or
+report correctly contained local scrolling. Review the actual cause and task
+context rather than hiding overflow to silence the finding.

package/references/routing.md

@@ -6,6 +6,7 @@ override user authority or grant permission for unrelated operations.
 
 | Question / when | Audience | Prerequisite | Source of truth | Verify with |
 | --- | --- | --- | --- | --- |
+| What needs saying? New or edited interface copy and reference adaptation | Designer / developer / agent | User task, product vocabulary and actual capabilities | flood-interface-content/SKILL.md | Contextual keep/rewrite/move/remove decisions; meaningful hierarchy; preserved recovery and accessible names |
 | Which primitive owns this role? Component/composite UI work | Developer / agent / reviewer | Matching catalog and component anatomy | flood-composition/SKILL.md | Reuse existing primitives; extend small capabilities first |
 | Which API can I import? Every component edit | Developer / agent | Installed exact versions | Installed @flood-md/react declarations; flood.json | Type-check host imports; CLI doctor for alignment |
 | What does this release mean? Setup / upgrade | Developer / agent | Matching guide | flood/DESIGN.md, package changelog | Compare version and declarations; preserve host edits |

package/references/spacing.md

@@ -41,6 +41,9 @@ the relationship between indicator and label, and independent form semantics.
 Avoid negative margins or transforms that conceal a layout problem or overlap
 click targets. For nested surfaces, compare inner radius with outer radius minus
 padding and stroke; independent controls retain their own radius recipe.
+When a circular avatar sits against the rounded end of a pill control, use the
+same inset at the top, bottom and avatar-side edge. Keep the label gap and the
+trailing action inset separate from that geometry.
 
 ## Check the composition
 
@@ -59,3 +62,30 @@ host's verification workflow; add a regression check for a repeated failure rath
 than a test that merely repeats a CSS declaration. Report what was measured and
 what remains unverified. See [accessibility](accessibility.md) and
 [verification](verification.md) for related contracts.
+
+## Judge the space you can see
+
+1. Name what should read together, what starts a new group, and what should
+   catch the eye first. Start with shared edges and the actual reading order.
+2. Inspect the screen at its working size. Compare the painted edges of text,
+   icons, fills and rules as well as their layout boxes. Line boxes, internal
+   padding and hit areas already contribute space. A strong fill or divider
+   also changes how much separation the eye sees.
+3. Compare two plausible treatments with the same content and viewport.
+   Change one lever at a time: space, measure, weight, tone or a boundary.
+   Pick the token that makes the intended grouping read clearly, then recheck
+   with the actual token applied. Keep stable alignment for repeated elements.
+4. Compare short and wrapped content and the presence or absence of optional
+   content. Recheck narrow layouts, enlarged text and text spacing overrides.
+   Keep focus visible, hit areas usable and reading order intact.
+
+For example, if a heading appears closer to the previous section than to its
+own controls, inspect the heading line box and the first control's top inset
+before increasing the section gap. If an icon looks off-center inside a
+centered slot, compare its visible outline with a sibling icon before adjusting
+the icon artwork. Keep the slot and click area on the shared track.
+
+In review notes, name the visual problem, the competing treatments and the
+reason one reads better. A passing geometry check supports that judgment.
+For text beside an icon, inspect the actual baseline and visible glyphs,
+including accents and wrapped labels. [CSS Inline Layout](https://www.w3.org/TR/css-inline-3/#leading-trim)