@flood-md/agent 0.2.9 → 0.2.11

package/references/customization.md

@@ -18,6 +18,20 @@ Keep reference values separate from semantic roles. Component recipes consume
 roles, and screen composition consumes components. An accent/material experiment
 must be scoped; it must not silently alter ordinary fields, text or focus.
 
+Filled material owners establish contextual neutral recipes for their children.
+Customize context-filled/base roles for a shared change; a direct consumer-role
+override on the owning material can refine that one scope. Verify canvas and
+elevated recipes together when increasing boundary contrast. Do not override
+surface.canvas to soften nested controls: it also supplies contrasting content
+and document/media wells. Use surface.current and the contextual supporting or
+readonly roles for those jobs. Explicit data-flood-surface attributes change
+context only, not the rendered material or overlay behavior.
+
+For a tinted theme, map the floating surface, translucent floating surface,
+floating border and floating selection alongside canvas and base/filled field
+roles. Open a Select on both canvas and a filled surface and check its trigger,
+panel and highlighted option. Check the opaque fallback as well.
+
 Keep layout/typography in rem, role line heights and tracking intact unless the
 task explicitly changes them. Never impose a root 16px or 62.5% reset. Bundled
 Inter retains its OFL notice; external icon/font assets keep their own notices.

package/references/flood-composition/SKILL.md

@@ -5,11 +5,20 @@ description: Build or review Flood UI from existing library primitives before ad
 
 # Compose Flood from its primitives
 
+When adding a reusable component or changing its visual contract, read
+[component families](../component-families.md) before choosing anatomy, sizing,
+shape or states. It governs Flood's own components as well as host composites.
+
 Existing Flood components are the building blocks, including inside other Flood
 components. Preserve their anatomy and behavior when improving a composition.
 Read the governing project instructions, matching declarations and relevant
 component guide first. This skill grants no additional permissions.
 
+When introducing visible interface text, apply the
+[interface content skill](../flood-interface-content/SKILL.md) before filling
+optional headings, descriptions or helper slots. Existing user-authored content
+is not permission to rewrite it during an unrelated layout correction.
+
 ## Choose the smallest existing owner
 
 Before changing JSX, identify the visible roles and their existing owners:
@@ -18,6 +27,31 @@ metadata, IconButton for an icon action, Dialog for modal behavior, Text/Heading
 for typography, and the appropriate form, list or table primitive for semantics.
 Check the actual installed exports and props; do not invent APIs from newer docs.
 
+Search the installed catalog by the role before settling on a low-level building
+block. Read the selected contract and compare a more specific owner when one
+exists: Metric for a labelled statistic; DatePicker for ordinary date selection
+with typing and a calendar, DateField for an explicitly entry-only interaction;
+StatusIndicator for a named state. Input type="date"
+invokes the browser's picker, not Flood's Calendar. Use it only for an explicit
+native-picker requirement or a documented limitation of the installed controls.
+Heading/Text remain valid for ordinary prose, not a default replacement for an
+available statistic component.
+
+Include layout and secondary interactions in that selection: Grid for repeated
+form tracks, Stack/Inline for related layout, AlertDialog for a discard/delete
+confirmation, and Alert/StatusIndicator for the appropriate feedback role.
+window.confirm/alert/prompt are browser UI, not Flood components. A small scope
+does not justify replacing an available owner with native UI or a parallel CSS
+grid. Keep native form, table and semantic document/shell elements where they
+supply structure; styling the host shell is different from reimplementing a
+provided layout or control. Document a genuine missing capability before using
+a project-owned adapter.
+
+Record the selected owner and any rejected match before implementing the surface.
+If discovery finds no suitable component, state the missing capability; do not
+claim that the library has no owner without checking. Keep this decision record
+in development notes, never as extra explanatory text in the product.
+
 - Reuse the matching component with its supported props and tokens.
 - If spacing or alignment is wrong, inspect both the primitive and the parent
   composition. Fix the owner of the relationship. Keep the primitive intact.

package/references/flood-data-display/SKILL.md

@@ -5,13 +5,61 @@ description: Assemble Flood tables, lists, cards and file records with long or c
 
 # Compose meaningful data structures
 
+Enable selection when it has a real consequence: a bulk operation, comparison or
+another requested selection task. Do not add checkboxes merely because the table
+supports them. Exercise the resulting action with the actual accepted scope.
+
+For search, multiple conditions or saved query definitions, read
+recipe:collection-views from the installed catalog when available. Separate the
+working query, an uncommitted condition draft, a named saved definition and the
+result/selection state. Save filters and supported sort, not result IDs. Name-only
+edits must not commit dirty filters; deleting a view must not delete records.
+Reset/revalidate page and selection when the query changes. Preferences read
+failure need not hide an independently loaded collection, but must block writes
+to that failed store and must not be disguised as an empty saved-view list.
+
+Use CollectionViewSwitcher for accepted view choice and applicable commands,
+separate from CollectionToolbar's working query controls. Offer update only for
+an editable changed definition; keep rename name-only. The component requests IDs,
+while the host owns acceptance, persistence and confirmation. Return naming and
+deletion dialogs to its selectRef when their original action may disappear.
+
+For one finite-choice property/operator/value row, use FilterCondition rather
+than reassembling differently sized controls. A property change clears the
+previous property's values in the proposed draft. Empty values are incomplete,
+not an instruction to broaden the accepted query. The host owns Apply/Cancel,
+duplicate-property policy and focus to another condition or Add after removal.
+Text/date/number predicates need a deliberate supported editor; do not pretend
+the finite-choice row implements arbitrary query semantics.
+
+FilterGroup composes those rows for a flat finite-choice draft. It owns row IDs,
+all/any controls and accepted row-change focus; the host owns Apply/Cancel and
+query evaluation. Preserve accepted rows when addition limits or duplicate
+policies change. Do not turn a new empty row into a broad accepted query or
+wrap an empty group in decorative onboarding. Keep group labels contextual;
+individual hidden legends/control names remain available to assistive technology.
+
 Use the installed component contracts and
 [composition workflow](../flood-composition/SKILL.md). Start with the content's
 relationships, not a wrapper around every piece of text.
 
+Keep visual/test fixtures separate from the host's working records unless sample
+data is explicitly part of the task. Do not seed a new user's persisted list with
+fictional business records just to fill a screen. Use isolated test state for
+populated screenshots and exercise the real empty state. When samples are required, identify their provenance in the test brief/README.
+A visible distinction is needed where it changes interpretation or action, such
+as sample records mixed with real records. Do not automatically add a permanent
+Demo badge to the shell of an explicitly requested isolated prototype; follow
+the interface-content workflow for contextual placement.
+
 - Table/DataTable preserve caption, headers, cell relationships and documented
   sorting/selection behavior. A footer represents a summary and should be
   visually distinguishable without relying on a heavy border everywhere.
+  Mark comparable quantities and amounts with DataTable column `numeric` or
+  Table header/cell `data-numeric` for logical end alignment and tabular digits.
+  Keep identifiers, such as postal codes and account numbers, aligned as text
+  even when they contain only digits. Preserve formatted units and use raw sort
+  values when localized text or rich cells would sort differently.
 - DescriptionList expresses named values; DataList/DataListItem express records.
   Card/Section/Surface organize groups without inventing a second typography or
   spacing system. A heading's semantic level does not prescribe its visual size.
@@ -23,6 +71,18 @@ relationships, not a wrapper around every piece of text.
 - Preserve native image alt/fallback semantics and aspect constraints. Decorative
   artwork should not duplicate an adjacent accessible identity.
 
+## Choose the information, not all available slots
+
+For record lists/details, apply the [records skill](../flood-records/SKILL.md)
+before filling metadata and actions. Identity, supporting context, lifecycle state,
+priority and timestamps have different purposes. Use Table/DataTable when users
+need several named comparisons; a trailing Inline of values is not a column model.
+
+Use Table for short static details, such as receipt lines. When DataTable owns
+sorting or selection and its result range adds no useful information, set
+`showResults={false}`. Keep the range when it helps explain pagination or
+the scope of filtered results. Selection feedback and page controls remain.
+
 ## Exercise data and geometry
 
 Test no records, one record, long/wrapping names, absent optional media/actions,
@@ -31,7 +91,96 @@ without inserting a second empty-state design or moving unrelated controls.
 Align file title/metadata and status/progress by their intended row relationship;
 do not hide a StatusIndicator dot or replace Progress with a custom track.
 
+For an editable table, compare the centre of plain amounts and row actions with
+the neighbouring input controls. Table centres record/action and editable rows
+by default; opt into cellVerticalAlign="top" only for deliberate prose alignment.
+Use the shared cellVerticalAlign contract rather than
+moving text with transforms or overriding Input, NumberInput or Button internals.
+Native style on an individual host-owned td/th can express an exceptional cell.
+Do not depend on a low-specificity descendant CSS override. Check the rendered
+centres; equal cell padding alone does not establish alignment.
+
+Also inspect readable column widths with long neighbouring records. A centred
+cell can still be wrong when a status or date is fragmented into single letters.
+Table and StatusIndicator preserve word-based intrinsic width by default; keep
+that recipe rather than applying global overflow-wrap:anywhere. Deliberate
+technical identifier cells can opt into data-wrap="anywhere". Otherwise use
+local scrolling or appropriate column budgets, not an empty no-overflow claim.
+
 Use the documented local overflow owner, with a meaningful accessible name. Focus
 the last action/cell and check that a rail or rounded corner does not cover it.
 Compare narrow/wide, enlarged text and RTL. Locale-sensitive text in prerendered
 examples needs consistent server/client locale to avoid hydration differences.
+
+## Declare remote and selection ownership
+
+Group collection controls by the task they affect. At a wide viewport, use the
+available inline space for related search and filter controls. Keep view selection
+and its management actions together, and make the result list reachable without
+passing several sparse control rows. Add a row when it improves grouping or is
+needed for wrapping, rather than assigning a row to each control type. Preserve
+logical reading and keyboard order when the same groups wrap at enlarged text or
+a narrow viewport. A collection host chooses the layout for its actual content.
+Match the heights and typography of fields and actions sharing a control row.
+Review the rendered sizes together. Keep management actions beside the view they
+affect unless the wider composition gives their separation a clear purpose.
+
+Default to at most two secondary filter controls beside a collection search.
+When more than two filter properties are available, put the secondary choices
+behind one Filters trigger. Count properties, including inactive filters, rather
+than counting component names. Search, view selection, sorting and record actions
+have different roles and do not count toward this filter limit. Keep applied
+conditions visible as removable summaries and keep Clear filters reachable.
+An explicitly primary filter can stay visible when the task warrants it. Move
+secondary controls earlier if their labels or enlarged text already crowd the
+row. Preserve draft/apply/cancel semantics and meaningful labels inside the panel.
+When its trigger supplies the shared context, a nearby value can omit repeated
+property text. A summary outside the panel needs its property named again.
+
+Use CollectionToolbar for the search/filter query row, with accepted summaries
+and a staged editor in filterContent. Keep saved views outside it. The fieldset
+uses normal Tab navigation; do not place its editable search in a roving Toolbar.
+Reuse FilterGroup for finite-choice drafts. The host owns validation, Apply,
+Cancel, request execution and reset scope; canClear must include quickFilters
+state when that slot is used. Preserve any-match meaning in summaryPrefix.
+Inactive Clear filters reserves space and leaves the accessibility tree. Removal
+and reset focus the persistent Filters trigger, or search without a panel.
+
+DataTable supports ready/loading/error states. Use emptyContent to compose
+EmptyState and a meaningful next action inside a ready empty table instead of
+removing its headers. Distinguish no records from no matches; only the latter
+offers reset of an active query. Custom empty content must not stand in for a
+read failure or pending request. After reset removes the action, focus a persistent
+query control. Omit emptyContent for the ordinary labels.empty message.
+
+Client DataTable receives the complete local collection. Server paginationMode
+receives one already sorted page, controlled page/onPageChange and totalRows;
+sortable server columns require controlled sort/onSortChange. Do not locally
+slice or sort a server page. Reconcile page when a filter reduces its total.
+The host owns query identity and abort/request generations so a late response
+cannot replace the current query. Present loading/error explicitly rather than
+labeling old rows as an accepted new page.
+
+Server page selection covers supplied rows only. Dataset scope requires controlled
+selectedIds and host validation of IDs beyond that page. Select-page never means
+select every search result. Clear/revalidate selection on query or permission
+changes. Capture confirmed IDs and keep the proposal after an operation refusal.
+Use BulkActionBar for a compact selected-record command rail; it composes
+Toolbar and OverflowActions and keeps one row with a pill exterior. Prefer two
+visible commands; at most three, with lower-priority commands in More. Use a
+general Toolbar for unrelated editing controls rather than adding them here.
+Show the actual selected count, distinguish page selection from the collection
+scope, and keep clearing selection separate from resetting filters. Confirm
+consequential actions against a captured list of IDs. Pending work targets that
+snapshot even if the visible query changes. On success remove only those IDs
+from current selection and reconcile pagination. Preserve accepted records and
+selection after rejection, and retry the captured proposal. Give disappearing
+action bars an intentional focus destination. Keep confirmation dialogs outside
+the Toolbar's roving descendants.
+A floating selection bar can keep record layout stable while selection changes.
+Anchor it to the viewport with safe-area spacing and a bounded width. Measure
+actual height and reserve scroll clearance so final rows and pagination remain
+reachable. Verify its menus near the viewport edge and keep modal confirmation
+in the dialog layer.
+Read recipe:record-workspace from the matching installed catalog for a working
+composition and its limits.

package/references/flood-feedback/SKILL.md

@@ -10,6 +10,11 @@ visible role before choosing color: StatusIndicator names a state, Badge marks
 metadata, Progress describes task progress, Meter describes a bounded measurement,
 Alert gives contextual feedback and EmptyState explains missing content.
 
+For several record attributes, use the [records skill](../flood-records/SKILL.md).
+A category called Error is not a failed operation; priority is not lifecycle state.
+Choose the semantic owner before its appearance, and keep essential triage data
+visible even when reducing decorative emphasis.
+
 ## Keep one owner for each message
 
 - Status text must distinguish pending, success, failure, cancellation and local
@@ -24,14 +29,55 @@ Alert gives contextual feedback and EmptyState explains missing content.
 - Spinner retains a meaningful accessible label where standalone. Skeleton is
   decoration, not another announced task. Preserve the existing reduced-motion
   behavior without introducing a new animation system.
-- EmptyState needs a reason and an appropriate next action when available. Its
-  icon/illustration and action remain existing primitives with consistent geometry.
+- EmptyState identifies the actual condition. A title can be enough; add a
+  description only for new decision-relevant information, not an instruction
+  repeating a visible action. Its icon/action use existing primitives.
+
+## Scope feedback to its operation
+
+Associate a message with the operation and record that produced it. Preserve
+entered data after refusal and keep a useful error while that operation remains
+unresolved. A successful retry clears/replaces its failure. Explicitly discarding
+the draft ends that draft's save error; it must not follow the user to a list or
+another record. Ignore late results belonging to an abandoned operation.
+
+Do not solve this with an automatic timer inside Alert or by clearing every
+message on navigation. A collection-wide read failure can still block editing
+after changing views and must remain until resolved. The host's state model owns
+that distinction; the feedback primitive only presents the supplied state.
 
 ## Evidence
 
 Trigger the operation and observe each applicable transition, including failure
-and retry. Check optional description/action/icon slots, long messages and text
+and retry. Also follow failure → explicit discard → list → reopen a saved record;
+the abandoned draft's failure must be gone and the saved data unchanged. Distinguish
+that from a still-unresolved collection-wide error. Check optional description/action/icon slots, long messages and text
 enlargement. Keep content visible without stealing focus merely to announce it.
 Reserve feedback space in a demo when needed for a stable sample, not universally
 inside every production component. Report audible announcement behavior only
 when it was actually tested with the relevant assistive technology.
+
+## Distinguish persistence failures from emptiness
+
+Missing, valid, malformed, read-failed and write-failed are distinct states. A
+read/parse failure is not permission to initialize samples or overwrite records.
+Keep the raw snapshot where available and block editing/writes until recovery
+succeeds or the user explicitly replaces that collection. Offer a named retry
+and, when useful, a recovery export. A missing key can initialize an empty list;
+fixture records declared in a test brief must not mask read failure.
+
+A refused write preserves the last accepted collection and the current draft.
+Discarding that draft ends its own save error, not an unresolved collection read
+error. Accept results only for the current request/draft generation. These are
+host-state decisions; Alert itself does not read storage or own recovery.
+
+Describe the observed failure without inventing its cause. A refused browser
+write can mean quota, denied access or another storage failure; do not prescribe
+clearing data or freeing space unless that cause is actually known. Retain the
+draft and offer an applicable retry/recovery action first.
+
+Build write proposals without mutating the accepted collection or the current
+draft in place. A rejected save must not append history, change status or alter
+the next retry before acceptance. Retry should propose one operation, not repeat
+side effects from the failed attempt. When a read failed, do not present invented
+zero totals or an empty collection as if the data had loaded successfully.

package/references/flood-forms/SKILL.md

@@ -11,6 +11,12 @@ ownership. Read the matching DateField/DateTimePicker component guide for its
 specific civil-value and draft contract; [accessibility](../accessibility.md)
 documents associations and feedback.
 
+For an ordinary business date field, prefer DatePicker so users can both type and
+choose visually. DateField is the lower-level segmented editor without a popup;
+choose it for an explicit entry-only interaction or inside a composition that
+already supplies Calendar. Do not silently omit the calendar just because the
+brief did not enumerate every affordance of choosing a date.
+
 ## Assign ownership
 
 - Field supplies label/description/error associations through its render props;
@@ -31,6 +37,58 @@ documents associations and feedback.
   Host validation decides the error and useful message. Keep native constraints,
   invalid focus and the accessible message association coherent.
 
+For visual roles and rhythm, read the [hierarchy skill](../flood-hierarchy/SKILL.md).
+Fieldset legendSize="section" is for an independent section; a short form may
+need no inner heading. Field labels and values keep their documented sizes.
+
+## Group before laying out fields
+
+For settings with one Save action, keep a draft and the last saved values
+separate. Group related fields under named sections, validate the complete
+draft, and keep entered values available after a refused save. Reset returns
+to the latest saved values. Confirm a successful save only after the host
+accepts it. See `recipe:settings-workspace` for a working local example.
+
+Choose the form's reading order and semantic groups before placing controls in
+columns. Establish shared outer tracks, gap and group padding. Use a single Grid for
+related rows; do not narrow one numeric field in only one row merely because its
+value is short. Preserve corresponding vertical edges before optimizing widths. Related groups
+should share those tracks: do not independently choose a four-column grid above
+two columns below and assume their edges align. A group may span the whole layout
+when its content needs it; not every field should have the same width.
+
+For Flood record/settings forms without a denser host requirement, start with
+at most two field tracks per semantic group. Four metadata fields become two
+pairs rather than an automatic four-field strip. Use one track for a narrow group
+or long field. A denser table editor, filter toolbar or explicit host design is
+a different context; record why its structure needs more tracks.
+
+For two peer groups, use two equal outer tracks and subdivide each consistently
+when a group contains short related fields. A pair of two-field groups can read
+more clearly than four unrelated columns. This is a pattern to evaluate, not a
+rule that every form has two columns or an invoice-specific template.
+
+Keep a group's title, controls and supporting message together in reading and DOM
+order. Distinguish page, group and field roles without adding headings merely to
+fill containers. Compare shared leading/trailing edges and gutters in the rendered
+form, including absent descriptions, long labels and changed field values.
+
+Measure the controls' content edges, not only the Grid boxes. A full-width padded
+Surface containing two tracks and two separately padded Surfaces can use identical
+Grid props while their actual controls differ by one surface inset. Nested padding
+must participate in the same track budget. Compare corresponding first/second
+control starts and widths across those groups; matching outer containers is not
+sufficient. Do not insert an empty grid child merely to occupy an unexplained gap.
+For a concrete starting structure, discover recipe:grouped-form in the installed
+catalog. It demonstrates shared tracks and two-field peer groups in a workspace
+form. Adapt its grouping to the host; do not copy its business content or add
+unrequested sample records.
+
+Choose the number of field tracks from the width available to the form. A wide
+viewport can still contain a narrow drawer or a form squeezed by a sidebar.
+Verify the same field group in wide and narrow hosts at the same viewport width.
+Check reading order, control widths and labels after the group wraps.
+
 ## Exercise transitions, not just props
 
 Check entry, clear, incomplete drafts, invalid input, accepted/refused controlled
@@ -41,5 +99,27 @@ representation genuinely requires it. Do not silently replace user edits.
 FileInput cannot receive a fabricated FileList or ordinary controlled text value.
 Separate selection from upload transport and progress. Calendar/date/time controls
 represent their documented civil values; do not infer a timezone or server save.
-Show a real success only after the host operation succeeds. In a local example,
-state explicitly that changes are local.
+Show a real success only after the host operation succeeds. Explain consequential
+storage limits once where they matter; a local example does not require a banner
+or repeated captions about its implementation. Follow the interface-content
+workflow for placement and wording.
+
+## Search values and remote collections
+
+Selected chips supply a MultiSelect's visible context. Its empty query should
+not reserve a redundant placeholder row; account for actual action/caret space
+and let real search or overflowing chip content grow. Do not hide the combobox
+or its keyboard entry to force a fixed-height appearance.
+
+Combobox/MultiSelect submit selected IDs. Autocomplete accepts arbitrary text and
+submits that text; choosing a suggestion does not turn it into an ID field.
+Do not weaken a fixed-choice requirement merely to accept a failed search.
+Manual filtering requires controlled query (Autocomplete: value), optionsQuery
+identifying the accepted result and explicit loadState. Keep selectedOptions
+while result pages change. The host owns fetching, cancellation and stale response
+rejection; the control also prevents choosing options for another query.
+
+Keep errors/loading distinct from zero matches and provide onRetry when useful.
+Test Enter, Escape, blur, native reset, controlled refusal, IME, disabled/readonly
+and actual FormData. Query completion, selection and text editing are separate
+events. Do not announce success merely because a fetch callback fired.

package/references/flood-foundations/SKILL.md

@@ -26,6 +26,36 @@ applies the existing dark base; it does not start a palette, theme or motion red
 - Preserve rem sizing, the host root font, role line height and tracking. IconSlot
   owns explicit artwork dimensions; IconButton owns the accessible action/target.
   A large control does not mean an unconstrained SVG or oversized supporting copy.
+  Supporting disclosure can use a smaller IconButton iconSize while preserving
+  its control size, focus area and touch target. Do not size all glyph roles alike.
+
+Action icons are artwork with an explicit IconSlot size, not a plus, arrow or
+cross typed into the label. Font glyph bounds vary even at the same font size.
+Use the project's licensed icon pack or an original SVG in IconSlot; text-only
+actions can omit the icon. Keep real symbols that are content, such as currency,
+phone prefixes or mathematical expressions, as text. Inspect the actual artwork
+and its centre relative to the label at the chosen Button size.
+
+## Surface context
+
+Choose a material owner before tuning the nested controls. Surface, Dialog,
+Drawer, Popover, selection popups and floating action bars establish their own
+context. Neutral action fills, fields, selection and supporting elements adapt
+to that nearest owner. Preserve solid action prominence, feedback meaning,
+content contrast and the independent accent focus.
+
+Do not fix a dark secondary button on an elevated panel with a page-specific
+button color. Inspect the shared context roles and another consumer first.
+Avoid broad ancestor selectors: a nested Surface owns its own context, while
+a transparent layout wrapper inherits the current one. Material levels do not
+count DOM nesting depth. Never alternate light/dark fills for every wrapper.
+
+Review the same controls on canvas, default, raised, modal and floating surfaces.
+Include nested surface resets, top-layer menus, read-only/disabled fields,
+selection, supporting chips and progress tracks, not only Button screenshots.
+Check the opaque fallback when transparency is reduced or unsupported and
+system colors under forced colors. A token's alpha is not evidence of sufficient
+contrast: inspect the composited color over the actual backing content.
 
 ## Evidence
 
@@ -35,3 +65,16 @@ a Surface and a popup over that field; inspect long text and enlarged root text.
 Do not claim visual consistency from token names or matching hex values alone.
 See [customization](../customization.md) and
 [accessibility](../accessibility.md) for perception/override details.
+
+## Destructive action tone
+
+Button and IconButton accept tone="danger" for an actual destructive command,
+independent of solid/subtle/outline/ghost prominence. It uses existing semantic
+color roles in FloodRoot; keep the normal accent focus and disabled behavior.
+A red label is not confirmation or permission to delete. Preserve that intent
+when OverflowActions moves the command into Menu.
+
+A numeric stepper is one horizontal control, not three wrapping fields. Keep its
+minimum action/value budget inside a dense table's local scroll region. Test the
+actual control at enlarged text in its narrowest repeated track; widening an
+unrelated outer wrapper is not evidence that its internal geometry is sound.

package/references/flood-hierarchy/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: flood-hierarchy
+description: Establish visual hierarchy, shared form tracks and vertical rhythm in Flood screens, forms and overlays. Use when titles, groups and labels compete or a composed interface feels flat; not a fixed page template.
+---
+
+Use PageHeader for the page's main heading and page-wide actions. Use Section
+for a named block within the page. Keep breadcrumbs outside the header and
+collection filters next to the collection. Add supporting copy only when it
+changes what the user can understand or do on this page.
+
+# Structure before emphasis
+
+Start with the user's task, reading order and installed component contracts.
+Distinguish the task title, genuinely independent groups, field labels, input
+values and actions before choosing their size or color. A short form may need
+only its task title and labels. Do not add a legend, subtitle, card or divider
+merely to create visual levels. Meaning comes from the interface-content workflow;
+this workflow makes that meaning visible.
+
+## Assign each relationship to its owner
+
+- Dialog owns its task heading and the body inset. Its dark title uses the
+  dialog-title role (1.25rem / 600); it is distinct from compact popup captions.
+- Field owns the label-to-control relationship: space-1 (.25rem) in the dark
+  profile. DateField/TimeField already use that relationship. Leave room between
+  independent fields instead of increasing the gap inside every label/control pair.
+- Field labels use field-label typography (.8125rem / 500) and readable primary
+  content color. Do not shrink every label or fade necessary labels to manufacture
+  hierarchy; units, required markers, errors and accessible associations remain.
+- Fieldset defaults to a compact label-sized legend for related choices. Use
+  legendSize="section" for a necessary independent form section: group-title
+  typography (1rem / 600) and space-4 before its fields. A legend is still a native
+  group label, not a new document heading level. Optional hint/choice relationships
+  keep their compact component-owned spacing.
+- Grid owns common tracks; Stack and Inline own relationships between fields,
+  groups and actions. Never duplicate component anatomy with styled text.
+
+These are installed recipe defaults, not permission to use missing APIs in an
+older package or to override private selectors in a host stylesheet.
+
+## Establish a shared frame
+
+Use one Grid for related rows that should share vertical edges. Two equal tracks
+are a useful starting point for four short fields; long names and descriptions
+can span the width. Numeric content being short does not by itself justify a
+narrower track in only one row. If a specialized width is necessary, preserve the
+common grid or deliberately separate that group and check its visual relationship.
+Do not repair a whole-frame mismatch with manual widths on individual controls.
+
+Choose the user's reading order first. In an ordinary date/time form, a pair of
+calendar and time controls can share tracks with a later pair of duration/status
+controls. This is an example, not an appointment-specific template. Independent
+semantic grouping can justify another order. Do not turn every group into a box.
+
+## Choose a rhythm, not a uniform gap
+
+For a compact settings form, start with the page heading, section legends,
+and ordinary Field labels. Check that each level is recognizable by size,
+weight and proximity. Use space-6 between sections as a starting point.
+Repeated switch rows already provide a full hit area. Keep those rows close
+and align the switches on one shared edge within a readable column.
+Check actual row centers and wrapping at enlarged text.
+
+Keep a label visually nearer its control than the next field and a group title
+nearer its own fields than the next group. Inspect the rendered line height,
+control padding and fill before adjusting a parent gap. Dialog already supplies
+its body inset. Compare one change in size, weight, contrast, or spacing at a
+time using the [spacing review](../spacing.md#judge-the-space-you-can-see).
+
+Treat action order/alignment as part of the task. An end-aligned cancel/primary
+pair can finish a short desktop dialog clearly. This is not a universal order:
+respect host conventions, direction, destructive confirmation and keyboard flow.
+Do not add a footer surface or separator unless it resolves a real boundary.
+
+Choose the strongest action within the current task region. Check the page,
+each repeated row and any open overlay separately. In a settings form, Save
+can lead and Discard can stay secondary. In a filtered empty list, clearing
+filters may become the most useful action. A read-only detail can have no
+primary action. Keep the intended next action recognizable across states.
+
+Record lists and details need an information budget as well as type hierarchy.
+Use the [records workflow](../flood-records/SKILL.md) for metadata placement,
+comparison columns and status/category/priority meanings; do not give every
+attribute equal visual emphasis.
+
+## Verify the relationships
+
+Read the actual title/group/label styles; inspect the rendered result rather
+than comparing font-size declarations alone. Check complete text and long values,
+not only empty inputs. Measure the left/right edges of corresponding controls
+across rows, including nested padding and optional fields. A shared outer Grid
+alone is not proof that the input edges align.
+
+At the host's desktop baseline include 1280px with 24px root text as well as
+normal 1280/1440px views. Ensure the final action remains reachable if the dialog
+needs to scroll. Open actual date/selection popups: a calendar needs readable
+content width even when its anchor is narrow; a selection list has a different
+width contract. Keep viewport collision limits and nested Escape/focus ownership.
+
+Report the consequential choices and actual evidence outside the product UI.
+An empty inspector result does not establish hierarchy, necessary copy or visual
+quality. Preserve a failed clean run; improve the library/guidance owner before
+starting a fresh evaluation, rather than editing the historical result.