@flood-md/agent 0.2.9 → 0.2.11

package/references/flood-interface-content/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: flood-interface-content
+description: Write or review Flood interface content with editorial decisions about copy, labels, hierarchy and states. Use for visible UI text and reference adaptation; not typography styling, campaigns or rewriting user documents.
+---
+
+# Edit the information, then the wording
+
+Read the task, existing product vocabulary and the relevant component contracts.
+Keep the requested audience, language, surface and scope. A test host is not an
+invitation to add a product story, onboarding, promotional banners or new flows.
+User-authored records and document bodies remain data; changing interface copy
+does not authorize rewriting them.
+
+## Give every text element a job
+
+Before adding copy, identify the user's current task and state. Each visible
+string should identify an object or control, distinguish choices, supply needed
+input guidance, explain a relevant consequence, report a real state or support
+recovery in the current task/state. A fact being potentially useful someday is
+not sufficient. If its removal changes none of those, remove the element rather than
+replace it with another friendly sentence.
+
+Make the decision in context:
+
+- **Keep** a necessary label, distinction, constraint, consequence at the relevant decision or recovery step after a real failure.
+- **Rewrite** an ambiguous or inaccurate message using the product's terms.
+- **Move** secondary, occasionally needed information to a relevant help surface.
+- **Remove** duplication, routine interface narration and filler added to fill space.
+
+Do not turn this into a shortest-copy contest. A longer explanation can be the
+correct choice for an unfamiliar decision, an exceptional state or a material
+consequence of an action being considered here. An ordinary list/editor is not a
+storage-selection or data-deletion decision: do not add a standing browser/storage
+warning just because clearing browser data could lose records. Put implementation
+limits in documentation/help; explain deletion/replacement consequences before
+the applicable action and actual persistence failures when they occur.
+Do not hide essential instructions or risks behind a tooltip merely
+to make a screen quieter. Preserve accessible names and associations when reducing
+visible copy; use the component's documented hideLabel API where appropriate.
+
+## Separate prototype provenance from product state
+
+An explicitly requested local prototype or fixture-backed test app does not need
+an always-visible Demo, Prototype, Local only or Test environment badge merely
+because of its development context. Put that provenance and its implementation
+limits in the project README, test brief or review handoff. Do not fill a sidebar
+footer, header or empty region with a reminder, or replace a removed badge with
+a differently worded banner.
+
+Keep a visible distinction when it changes a decision on this surface: sample
+records mixed with real records, a meaningful selectable simulation mode, or an
+action whose effect/destination differs between environments. Place it beside the
+affected record, choice or action. Do not invent a mode switch or warning flow to
+justify an environment label. An isolated prototype is not a mixed live workspace.
+
+Removing prototype chrome does not authorize claims of real live video, delivered
+messages, production connectivity or other unimplemented capabilities. Keep
+accurate object/media accessible names and action wording; document the simulation
+in the handoff. Real Draft/Pending/Offline record states are not prototype labels
+and must not be removed by a word-matching rule.
+
+## Keep one vocabulary and an honest hierarchy
+
+Use the user's domain nouns and existing action terms. Name destinations by what
+they contain and actions by the result they cause. Avoid vague completion labels
+when several outcomes are possible. A validation check does not establish expert
+review; preparing a document does not send it; exporting a PDF does not create a
+restorable backup of editable records.
+
+A page title identifies its task or object. Add an eyebrow or subtitle only when
+it conveys another useful distinction. Do not automatically stack a category,
+the same category in a title, and a sentence describing that title. Section titles
+name actual groups; they do not each require an explanation. Semantic heading
+levels reflect the document structure, independently of visual sizing.
+
+Keep necessary repetition across different contexts: a dialog may need the
+affected object named again, a long form may repeat its primary action at the end,
+and a printed document has its own content hierarchy. Do not remove those merely
+because similar words appear elsewhere on the screen.
+
+Review shared context across the shell, page header, toolbar, list and open
+record. A page title can carry the task, a section can name the collection, and
+column labels can carry units or field meaning. Trace each repeated fact to its
+visible owner. Temporarily remove optional subtitles, count captions and labels
+beside values. Restore a string when its absence hides scope, changes a decision
+or makes a pane ambiguous when it opens on its own. Keep names required by
+assistive technology when the corresponding visible caption goes away.
+
+## Explain only what changes a decision
+
+Prefer a clear label or unit to an added helper paragraph. Add a field hint for a
+non-obvious format, source or choice; do not narrate typing or repeat its label.
+Technical properties of the implementation belong in developer documentation
+unless the user is making a decision about them. A document preview usually
+does not need a caption about embedded fonts or selectable PDF text.
+
+Check actual behavior before writing states:
+
+- Errors say what failed and how the user can recover, without raw exception text
+  or unsupported assurances. Keep entered data and associate errors with controls.
+- Success names an operation that actually completed. Avoid celebratory filler
+  and repeated announcements for routine edits. The feedback workflow owns timing.
+- Empty results and a first-use empty collection are different states. Use the
+  shortest useful explanation and next action for the actual case.
+- A sample-data label is justified when it prevents a real misunderstanding.
+  Put it where that distinction matters. Do not repeat demo disclaimers throughout
+  a test interface whose context is already established.
+
+For list/detail metadata, apply the [records workflow](../flood-records/SKILL.md).
+Use its decision examples to distinguish useful priority/recency from redundant
+labels and counts; the right amount of information depends on the user task.
+
+## Adapt reference content by purpose
+
+For each reference pattern, identify the question it answers and the capability
+that makes its wording true. Transfer that relationship to the host's actual
+objects, actions and states. Do not transplant a competitor's role names, approval
+stages, promises, regulatory language or marketing line into a different product.
+If the host has no equivalent capability, omit that element rather than invent one.
+
+Borrowing a two-pane editor does not imply borrowing an OCR claim or a payment
+workflow. Product references inform structure; user records and confirmed product
+facts supply content. Keep unavailable capabilities explicit in guidance, not as
+decorative warnings on every screen.
+
+## Review the composed surface
+
+Default optional subtitles and descriptions to absent. A page title plus its
+primary action normally needs no sentence narrating that action. An empty-state
+title identifies the missing content; it is not a slogan. Add explanation only
+when it changes the user's next decision or supplies a needed constraint.
+
+After rendering, identify each supporting sentence's new information. If it only
+restates the title, predicts obvious typing/calculation, or repeats another help
+location, remove it. Read the decision examples when uncertain; reading this
+workflow without applying that review does not satisfy it. Preserve essential
+consequences and actionable errors rather than stripping every explanation.
+
+Read the whole screen in task order, including navigation, heading, fields and
+actions. For a collection, repeat with populated and empty results, then with the
+record open. Compare count scope before dropping duplicates. An active filter
+count and a footer range may differ when search or pagination is active. If all
+receipts are already visible in their column, omit a routine completion caption;
+keep a missing-receipt signal if it affects approval. Name totals when two
+simultaneously visible amounts represent different scopes.
+
+Review visible strings together with accessible names, placeholders and
+announcements. Removing a subtitle should also remove its reserved space.
+
+For a writing pass, report the consequential keep/rewrite/move/remove decisions
+outside the product UI, and exercise the affected action or error. Automated
+phrase scans cannot establish editorial quality. Use [decision examples](../interface-content-examples.md)
+when a similar-looking string needs different treatment in another context.
+Do not claim an independent agent evaluation when the author already knows the
+implementation or corrected the initial output manually.
+
+## Make canonical examples teach the same standard
+
+Apply these decisions to playground defaults and copied recipes. Optional
+descriptions start absent. When demonstrating one, use a real distinction or
+constraint, such as a plan's member limit, rather than a friendly sentence
+repeating its title. Marketing prose belongs to a deliberate marketing surface,
+not default field/dialog content. Review the printed example as well as its DOM.

package/references/flood-motion/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: flood-motion
+description: Design and verify motion for Flood controls, overlays, disclosure, feedback and loading states. Use for animation, transitions, reduced motion and component motion reviews.
+---
+
+# Choose the event before the animation
+
+Read the installed motion tokens and the component's behavior contract.
+Choose motion by what changed and how far the eye needs to travel.
+
+| Event | Flood recipe |
+| --- | --- |
+| Hover, press, current or checked | Brief paint transition. Standalone controls may compress slightly while held, then return to rest. Selection can move a glyph or thumb that represents the state. |
+| Disclosure | Change content availability immediately. Rotate the indicator and reveal newly shown content only where the component owns that region. |
+| Anchored popup, modal or drawer | Start from the anchor direction, a small opacity change, or the drawer edge. Larger layers get more time. Dismissal should be shorter where the lifecycle can preserve it safely. |
+| Progress, loading or result | Animate the indicator or arriving message. Keep text and state legible during the motion. |
+| Focus, validation, drag, resize, scrubbing or text input | Immediate focus, feedback and geometry. The pointer and selection own their position. |
+| Typography, layout and static content | Inherit motion from the interactive owner. Avoid mount effects on structural wrappers and ordinary rows. |
+
+Use Flood semantic timing roles and narrow transition-property lists. Prefer
+opacity and transform on bounded visual parts. Keep an anchored overlay's
+positioning root stable while a child moves. Animate color only where the old and
+new colors keep required information legible. Keep focus outlines and error
+messages immediate. Apply hover treatment only to devices that can hover.
+Keep compression off disabled controls, text editors and joined control
+surfaces. Verify release and cancellation without a layout shift.
+Treat disclosure headers as part of their enclosing surface. Keep their
+background flush during press and rotate the centered glyph around its own center.
+
+Keep focus, ARIA, routing, scroll locks and form state independent from animation
+completion. For native top-layer exits, verify that content, inertness and focus
+all remain correct. Use an immediate close when an exit would keep an empty or
+interactive shell visible. Rapid reversal must settle to the accepted state.
+
+Honor `prefers-reduced-motion: reduce` with immediate state changes and static
+loading indicators. Never require motion to distinguish two states. For infinite
+motion, verify the activity ends with its actual loading state.
+
+Review actual controls in the same screen and at their supported density. Verify
+pointer, keyboard, touch, interrupted transitions and reduced motion. For
+overlays, also check repeated open/close, focus restoration and nested dismissal
+in Chromium, Firefox and WebKit. Record deliberately static behavior by family.
+Use the Motion guide in the matching catalog for the component-by-component
+contract. When adding a component, give its states an owner in that guide.

package/references/flood-navigation/SKILL.md

@@ -11,6 +11,13 @@ object selection; Tabs for associated panels; Accordion/Collapsible for disclosu
 SegmentedControl selects one value and is not a tab panel controller. Do not use
 Menu just because links appear vertically.
 
+For the 0.2.11 source candidate, NavigationItem is the shared small row owner and
+NavigationGroup owns an optional section heading/action, separator and independent
+group disclosure. NavigationTree composes rows into a hierarchy; Sidebar owns
+fixed regions and bounded scrolling. Consumers must discover these APIs in their
+installed version before using them. Atomic composition separates responsibilities;
+it does not require a new export for every wrapper or spacing token.
+
 ## Preserve browser and keyboard behavior
 
 - Links retain real href, modifier/open-in-new-tab behavior and current-page
@@ -23,6 +30,58 @@ Menu just because links appear vertically.
   Avoid adding generic arrow-key handlers around nested interactive content.
 - Disclosure state must match its trigger and panel. Check whether content remains
   mounted, and preserve any native form/focus consequences of the installed API.
+- A branch with no destination can use one full-row disclosure button. A branch
+  with a destination uses a real link plus a separate sibling disclosure action.
+  Do not nest the toggle inside the link or make a normal link click also toggle
+  expansion. Command rows retain Button semantics; vertical navigation is not
+  automatically an application Menu.
+
+## Shared rows and configurable groups
+
+Use AppShell for workspace regions and AppTopBar for shared application
+context and actions. PageHeader belongs inside the main region. Sidebar and
+NavigationTree own the destinations and expanded branches. Keep the selected
+route, responsive presentation and a mobile Drawer's open state separate.
+Use AppShell navigationDrawer for a single dock that needs to switch based on
+container width. Verify the switch inside a narrow parent at a wide viewport,
+including resizing while a navigation link or the Drawer has focus.
+
+Hide the visible caption of a single group when its title repeats the app or
+workspace context. Keep the group's accessible name with `hideLabel`. Align
+visible captions with destination labels, and check both settled sidebar widths.
+
+NavigationItem owns the complete row surface, including the visual relationship
+between its primary control and disclosure. A shorter selected background behind
+only the label/link makes the trailing action look unrelated. Keep distinct click
+and focus targets within a coherent current/hover surface; current destination,
+ancestor-current, expansion and focus remain separate. Budget actual trailing
+anatomy once rather than adding another empty inset or column in the shell.
+Align disclosure and badge centers on the trailing track. The disclosure target
+already contributes half its width as clearance, so use the compact edge inset
+there and preserve the full target.
+Use trailing for noninteractive metadata and trailingAction for an independent
+named action. Keep both visible on the trailing track at rest and during
+interaction. On an already filled row, use a glyph-level hover response for a
+ghost accessory and keep its keyboard focus visible. Use branchGuides for dense hierarchies where
+indentation alone is hard to follow. Keep section separators optional and
+distinct from branch guides.
+Use Sidebar headerLayout inline when the expanded identity and toggle should
+share a row. Use the stacked recipe when the toggle must stay on the same axis
+through collapse and expansion.
+
+NavigationGroup starts with optional presentation empty. Add a heading to name a
+real group, headingAction for a real command, and separator for a relationship
+that needs one. Do not fill every slot to make a demo look complete. A collapsible
+group requires a label; hiding its visual label does not remove the disclosure's
+accessible name. collapseDisabled disables that disclosure, not its child links.
+Group expansion is not NavigationTree expandedValues and is not Sidebar compact
+state. A proposal callback does not prove the host accepted the change.
+
+Compact groups keep destinations available without requiring an invisible group
+toggle. Preserve the accepted expanded choice for the return to expanded mode;
+do not overwrite it merely to reveal compact destinations. Meaningful heading
+actions remain available. Test headed/unheaded groups, actions present/absent,
+separator on/off, accepted/refused collapse and compact transitions separately.
 
 ## Evidence
 
@@ -33,3 +92,139 @@ new line can indicate a sizing error rather than a legitimate responsive layout.
 For sidebar navigation, scroll/focus the final item and keep its selected surface
 clear of the scrollbar. Verify the actual navigation composition at narrow width
 and enlarged text; an isolated item's screenshot is insufficient.
+Verify shared inline tracks from header through footer: leading glyph center,
+text start and trailing badge/disclosure center. Group labels inherit the chosen
+text track. Missing peer icons reserve their column; iconless nested links use
+an intentional parent-text indent. Sidebar places its scrollbar in existing edge
+spacing, without a permanent extra column or a shift when overflow appears.
+Other scroll surfaces must still protect content that reaches their tracks.
+In compact mode compare the actual brand, pane-toggle, destination and account
+control centers against the full rail center. A balanced body or centered footer
+container does not prove its Menu trigger is on the same axis. Adapt the fixed
+identity/utility slots through the accepted compact state instead of inserting
+an unrelated small button and assuming inherited alignment will fix it.
+
+Use Sidebar for bounded workspace navigation: NavigationTree owns the destinations
+and disclosure, ScrollArea owns the middle scroll viewport, and fixed header/footer
+slots adapt through the collapsed render state. Give the host a meaningful height;
+do not add several competing scroll owners. Route/current value, compact width and
+branch expansion are independent controlled states. A callback is a proposal,
+not acceptance. Keep groups and item IDs stable; item values are globally unique.
+Collapsed branches open a full NavigationTree in Popover, not an application Menu.
+Leaf links preserve href and modifier behavior. Do not claim an active ancestor
+is the current page. Count metadata uses trailing with Badge; icons retain explicit
+IconSlot sizing. Compact destinations use Flood Tooltip on hover and keyboard
+focus while keeping their actual Link or disclosure button. Do not layer a
+native title with the same text over the tooltip. Suppress the branch hint while
+its flyout is open; tooltip behavior must not replace navigation or steal focus.
+Sidebar owns no routing, preference persistence, mobile drawer or keyboard shortcut.
+Add those in the host only for an explicit requirement. On a programmatic width
+change, keep surviving focus or restore it within the navigation; do not move
+unrelated outside focus. Verify footer reachability and flyout text at both widths.
+
+## Compose global and contextual navigation
+
+For a multi-domain application, distinguish global module choice, contextual
+page destination, branch expansion and context-pane visibility. A GlobalRail
+profile can compose a flat, permanently compact Sidebar; the adjacent ContextBar
+profile composes another Sidebar for the accepted module. Use distinct landmark
+names and keep global utilities separate from contextual destinations.
+
+Do not duplicate the context list in both an open ContextBar and a rail flyout.
+Re-clicking the active module does not implicitly hide its context: give that
+pane an explicit visibility control. Use currentKind="location" for a current
+global module and the default page kind for an actual contextual destination.
+Keep genuine hrefs and derive accepted routes from the host router. Modifier
+clicks/open-in-new-tab must not change the current tab's accepted module.
+
+Read recipe:navigation-workspace from the installed catalog for the full host
+composition. Keep filters/search scoped to the accepted module; resetting one
+module must not change another module's query. Validate complete route identities
+before deriving titles and current state. If a focused row/pane/action disappears,
+restore a stable host destination only after the previous focus was disconnected
+and focus fell to the document body. Do not reset surviving focus on every render.
+Include dialog-close after its original trigger disappeared in that check.
+
+SidebarGroup.hideLabel omits a redundant visual heading while retaining the
+named nav landmark. Start optional headings, captions, counters and helper slots
+empty; add them only for information needed for recognition or a decision.
+Group headingAction, separator and collapse configuration belong to the section;
+Sidebar headerSeparator/footerSeparator are independent opt-in shell choices.
+Do not equate every group boundary with a visible line.
+Use the live workspace composition before introducing separate public aliases:
+an identical wrapper name is not a new component responsibility.
+
+Keep a shared top reading anchor across composed panes. A header without a
+collapse action still needs the family header height; removing an optional button
+must not shift its entire navigation above the neighboring rail.
+
+Evaluate the navigation with its main workspace at real desktop width and height,
+not only as a centered object in a docs column. Keep visible chrome subdued
+relative to task content, expose current destinations clearly, and budget badges.
+Record deliberate scoped semantic theme overrides rather than styling around
+the reused primitives. Evidence from another product informs a decision; it does
+not authorize copying implementation or presenting an undated page as a new release.
+
+## Give navigation a deliberate visual grammar
+
+NavigationItem owns a row, not a hidden hierarchy. For a compact row that has
+both a destination and children, use NavigationTree's branch composition: its
+flyout retains the parent destination and the children. Do not hide one of two
+actions merely to fit an icon target. Keep Tooltip mounted and disable its hint
+while the interactive flyout is open; replacing that wrapper can remount the
+trigger and break focus return.
+
+Separate destination artwork from supporting disclosure. Use the IconButton
+iconSize capability to reduce a chevron independently of its size/hit area;
+never shrink the clickable target just to make the glyph quieter. Compare the
+actual artwork, not merely its SVG box. Sidebar's sm/md disclosure uses 2xs
+artwork, lg uses xs; these are the current family recipe, not universal pixel
+requirements for every action. Keep the shared trailing action center.
+
+A pane toggle depicts the pane, with distinct open/close directional states.
+A multi-panel layout icon is not automatically a recognizable visibility action.
+Keep its accessible name and aria-expanded synchronized with the accepted state;
+resolve side and RTL before choosing the arrow direction. Check inherited
+direction changes after mount too: panel edge, arrow and flyout side must update
+together without requiring an unrelated interaction to refresh them.
+
+Do not make every relationship a new pill, divider or group title. Peer items,
+children, separate groups and fixed footer actions need distinct parent-owned
+spacing. Start optional captions, counters and descriptions empty. Give each
+visible addition a recognition, navigation or task purpose; remove decorative
+status claims and labels that repeat their inherited context. Apply the content
+workflow to the actual rendered navigation, including hidden and empty states.
+
+A professional result requires both a coherent family and a working interaction.
+Review expanded/compact side by side with real short/long labels and a populated
+workspace. Check whether a user can identify destinations, discover hidden labels,
+change the current route and reopen a pane. A generic "anti-slop" checklist or
+passing build is not evidence that these rendered checks passed. Learn from
+references without importing another product's branding or taste bans wholesale.
+
+## Coordinate actions and workspace anchors
+
+For a persistent pane toggle, keep its viewport position while its pane changes
+width or visibility and test consecutive clicks at the same coordinates. If a
+compact rail swaps the service mark for the toggle, keep both in the same slot
+and reveal the toggle on hover and keyboard focus. Keep the toggle visible on
+devices without hover. When context is hidden, a rail module can open its
+destinations in a compact NavigationTree flyout. Keep links and expansion state
+shared with the docked context. Escape dismisses the flyout without changing the
+route or pinning the pane.
+
+For a rail hover preview, use the compact item's flyout options. Opening from
+hover preserves focus and allows the pointer to cross the gap into the panel.
+Explicit activation still opens the same destinations on keyboard and touch.
+Anchor a tall context flyout to the rail so it shares the workspace top edge.
+
+Menubar coordinates desktop commands and one open menu, not website destinations.
+Reuse Menu for its child menus; native links still own destinations. OverflowActions
+composes Toolbar/Button/Menu. Preserve command identity, disabled state and danger
+tone when moving into More. Choose priorities by task, not label length. Exercise
+focus when resize hides an action or removes the More trigger.
+
+Keep a common top reading anchor across short/long workspace pages. Use logical
+inline centering for content width: margin:auto on a grid child can also center
+a short page vertically. Name each pane's scroll owner. Check short/long lists,
+detail and editor at the same viewport; a Drawer/table cannot fix its parent.

package/references/flood-overlays/SKILL.md

@@ -10,6 +10,9 @@ Use the actual installed overlay and trigger contract; see
 noninteractive help; interactive content needs the appropriate Popover or dialog.
 Do not put an action inside a tooltip or apply application-menu roles to site links.
 
+For a short Select trigger, verify that the open list can fit the longest
+ordinary label, then repeat near the viewport edge with a very long label.
+
 ## Preserve trigger and state
 
 Forward trigger props/ref onto one mounted native action. Preserve its accessible
@@ -17,16 +20,55 @@ name and open/controls semantics. Choose host-controlled open state or a default
 and test a host refusing an open/close request. Do not claim control state changed
 merely because a callback ran. The host owns persistent values in unmounted panels.
 
+Tooltip can attach to a real Link or Button through HTMLElement-safe trigger
+props. Preserve the ref, hover/focus handlers and descriptions together with the
+host handlers. Do not turn a navigation link into a button to add a hint. Raw
+tooltip buttons in forms keep an explicit type="button". A control sharing Tooltip
+and Popover composes both refs and suppresses its hint while the popover is open;
+the interactive layer owns Escape and focus then.
+
 Modal and nonmodal focus are different: do not add a trap to every floating
 surface or remove a modal's background inertness. Escape dismisses the active
 layer; a nested menu/select must not also close its parent dialog. Restore opener
 focus unless the host intentionally moved it elsewhere.
 
+Task Dialog titles and body insets use their own recipe; do not reuse compact
+popup caption typography for the modal task. The
+[hierarchy workflow](../flood-hierarchy/SKILL.md) owns title/group/field relations.
+
+Use CommandPalette for modal search. Its search header and results share one
+overlay surface. Forward the trigger and keep the modal title and input label
+specific to the task. Use loading for an in-flight request, and let the host
+control permissions, navigation and shortcuts.
+
 ## Inspect the actual host
 
+Use a Drawer for a short record task that needs the list as context. Use a
+route when the record needs a shareable address, substantial editing space, or
+its own navigation and history. After a Drawer save, restore the initiating
+control if it remains in the result set. Choose a stable list control when the
+edit changes filter membership. See `recipe:record-management`.
+
+Choose Drawer width using the longest real title, body copy and form controls.
+Compare `md` and `lg` with a populated record. Use the description slot for
+brief context and compose independent body sections with Section, Stack,
+DescriptionList or Fieldset as appropriate. Put the next action in the footer
+when it must stay reachable during scrolling. Avoid repeating the heading
+as a section name or showing two equivalent dismiss actions in a clean state.
+
+Overlay material establishes the nested neutral control context automatically.
+Compare its fields, secondary actions, selection and supporting chips with their
+canvas counterparts. Avoid opaque dark action islands or hiding the entire
+surface distinction behind a strong border/shadow. Glass needs an opaque
+fallback and a reduced-transparency path. A nested Surface resets its own
+material; a nested chooser becomes a new floating owner. Verify both cases.
+
 Check placement at viewport edges, resize, narrow/enlarged text, RTL and parent
 scrolling. Selection popups and calendar popups have distinct content geometry;
 use the supported field/anchor sizing behavior, not a universal fixed width.
+DatePicker calendar panels have a 20rem preferred minimum, bounded by available
+viewport width; narrow anchors need not force cramped calendar content. Selection
+lists and time lists retain their separate contracts.
 Verify nested radii/insets, surface distinction over a parent Surface and that
 essential content stays outside scrollbar rails. No clipping or noisy duplicate
 contours should be concealed with extra wrappers.

package/references/flood-records/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: flood-records
+description: Compose record lists and detail views with a clear metadata hierarchy. Use for crowded status/category/priority/date rows, drifting scan positions or deciding between a list and a comparison table.
+---
+
+# Select information for the current decision
+
+Read the task and installed DataListItem, Table/DataTable, DescriptionList and
+feedback contracts relevant to it. Start with what the user needs to recognize,
+compare or act on before opening a record. A record's available schema is not the
+content specification for every surface. Use the
+[interface-content workflow](../flood-interface-content/SKILL.md) for wording and
+[hierarchy workflow](../flood-hierarchy/SKILL.md) for visual relationships.
+
+Before JSX, make a short field -> decision -> list/detail placement record in
+development notes. Include the reason for an omitted field; do not place this
+planning text in the interface. Read the
+[decision examples](../record-decisions.md) when meanings or placement are unclear.
+
+## Choose the record structure
+
+- Use DataList/DataListItem when identity, a useful summary and opening the record
+  are primary. Keep the title and summary as one readable unit. Give secondary
+  attributes a subordinate relationship rather than filling every trailing slot.
+- If users compare several independent attributes across records, use Table or
+  DataTable with actual named columns. A long Inline of unrelated values at each
+  row end is not a substitute for comparison columns.
+- Use DescriptionList for named values in details. Each item requires a unique,
+  stable string `id` alongside `term` and `description`. A detail view can expose
+  more information than a list; it does not need to repeat the list's chip arrangement.
+- Selection is not navigation. A record list does not become ListBox merely
+  because users click its entries. Retain a real Link and independent actions.
+
+When a scan signal is useful at the trailing edge, keep its position stable
+across sibling records. Test the longest and missing values, not only equal sample
+strings. Multiple right-justified values with variable lengths produce shifting
+pseudo-columns even when their gaps match. Use an explicit common comparison
+structure or move secondary attributes into the copy area.
+
+## Distinguish metadata roles before styling
+
+| Meaning | Existing owner / treatment |
+| --- | --- |
+| Lifecycle or operation state | StatusIndicator with accurate text; color is supplementary |
+| Category, type or membership | Badge when a tag-shaped marker helps recognition; otherwise named/subordinate text |
+| Priority or urgency | Keep visible when it drives triage/comparison; use an explicit column or named value if needed |
+| Creation, update, due or event time | Identify the event and appropriate precision; do not treat every date as a status |
+| An available operation | Button/IconButton/Menu; do not make an informational badge look actionable |
+
+A category named Error is not necessarily a failed operation. Do not choose
+error styling or an announcement from that word alone. Use clear labels in
+ambiguous contexts, especially details with several similar-looking values.
+A priority is not a second lifecycle status. Do not make all attributes colorful
+chips or interchangeable status dots. Keep StatusIndicator rather than hand-drawing
+its state text/dot to fit a preferred arrangement.
+
+There is no universal badge limit. For a browsing list, start with identity and
+one useful scan signal; admit further visible metadata when it changes selection
+or action. For triage, priority may be essential even when every item is normal.
+Do not hide necessary comparisons just to make a screenshot quieter. Conversely,
+a default low/medium priority does not automatically need a separate visual accent.
+
+## Distribute information between list and details
+
+For a table row whose main action opens an in-place Drawer, use DataTable's
+`primaryAction` when the installed version provides it. Title and metadata
+share a compact cell, pointer activation extends across the row, and a native
+button provides the keyboard entry. Keep checkbox, links and menus independent.
+For a real destination, preserve a Link. Use the table toolbar and matching
+edge inset when the heading, filters, cells and footer share one surface.
+
+Give a queue's summaries only the prominence they earn in the task. If a
+count changes which work to pick up, make the relevant scope clear. If the
+table already exposes the decision, compare a quiet inline count with a
+separate metric surface before spending the first viewport on summaries.
+
+Classify a collection toolbar control by the thing it changes:
+
+| What changes | Owner |
+| --- | --- |
+| One selected value filters the same table | SegmentedControl for a few visible choices, Select when the choices need a compact menu |
+| The current panel and its associated content | Tabs |
+| The current destination | Link |
+| An operation runs | Button |
+
+For example, Pending and Reviewed can filter one table even when each state shows
+different columns. Use the installed SegmentedControl when its value model fits.
+Read its component contract before composing the toolbar. Keep one table and
+preserve applicable search and sorting; reset a page or close a detail only when
+the new result invalidates it. Keep focus on the selected control. Exercise arrow
+keys and check that the selected value updates the rows and accessible state.
+
+Protect enough width for the identity and useful summary. Category and recency
+can read as secondary information near the title; status may stay in a stable
+trailing position. This is one pattern, not a required arrangement. DataListItem
+slots accept composition from supported Flood primitives; check their actual
+content types before using them. Do not override private slot layout or wrap
+ordinary metadata in invented semantics merely to silence an inspector.
+
+In details, group named attributes by purpose. Place the principal state where it
+informs action; avoid an unlabeled strip of state, category and priority that asks
+the user to infer their meanings. User descriptions remain content, not interface
+copy to shorten. A heading or Surface around a description must earn its role;
+it is not mandatory for every text field.
+
+Creation and modification describe different events. Keep both when history or
+recency matters. If displayed values repeat and the distinction adds no current
+value, one visible date may suffice; if exact time matters, use adequate precision
+instead of suppressing the distinction based only on equal formatted dates.
+
+## Compose collection states deliberately
+
+Use the `recipe:record-management` material when users need to find a record,
+edit it and continue working through the same list. Keep the applied query,
+filters, ordering, page and scroll with the mounted collection. After saving,
+reapply the current filter to the updated data. If the source row disappears,
+return focus to a surviving list control such as search. In a long list, verify
+the scroll position and focus separately after both Save and Cancel.
+
+Keep search and a frequently used filter visible when there is room. Put
+occasional or grouped criteria behind a named Filters action. Show applied
+criteria at the list edge so users can tell why a record is missing.
+
+First-use empty, filtered no-results, loading and read failure are different
+states. Keep a relevant reset/action and meaningful feedback. A result count can
+help filtering or pagination; do not automatically add Found: 0 beside an empty
+collection message that already establishes there are no records. Never remove
+an accessible update announcement merely to remove a duplicate visible sentence;
+check announcement ownership in the feedback workflow.
+
+A product header, page title and section heading must answer different questions.
+Do not add a generic product/category eyebrow plus a title plus a sentence restating
+it just because the shell has slots. Real branding and navigation context can
+justify persistent chrome; preserve that purpose rather than applying a text ban.
+
+## Verify across several records and states
+
+Use isolated fixtures, not fictional records persisted into the user's app. Check
+several short and long titles, every meaningful state, differing category/priority
+lengths, missing metadata and long dates. Inspect scan positions and copy width
+at normal and enlarged text, including 1280px/root24px for the desktop baseline.
+No page overflow alone does not prove that the title has readable width.
+
+Open details and return; exercise filters, no-results/reset and row actions.
+Check reading order, Link names and action focus separately from visual alignment.
+Review each visible attribute's decision value outside the product UI. An optional
+observer may flag useful metadata or miss a crowded row; record the contextual
+keep/move/name/omit decision rather than treating its output as editorial approval.