{ "schemaVersion": 1, "scope": "Installed Flood React/Next.js projects", "rules": [ { "id": "api.installed", "when": "Importing or changing Flood APIs", "for": [ "developer", "agent" ], "requires": [ "Host package.json", "flood.json" ], "sourceOfTruth": "Installed @flood-md/react declarations", "guide": "references/routing.md", "verify": [ "Host type-check", "Matching CLI doctor for package alignment" ] }, { "id": "composition.primitives", "when": "Composing screens or forms", "for": [ "designer", "developer", "agent" ], "requires": [ "Supported installed exports", "User interaction requirements" ], "sourceOfTruth": "DESIGN.md", "guide": "references/composition.md", "verify": [ "Rendered narrow/wide screen", "Intrinsic actions and responsive form parent", "Close choice label and independent group spacing", "Reuse shared atoms while preserving specialized native semantics", "Selected role owners and their installed contracts recorded before JSX", "Actual date/selection popup checked against the selected component", "Container/grid/media geometry at the host's declared viewport and text targets", "No invisible focusable content without reveal behavior" ] }, { "id": "forms.associations", "when": "Changing fields or submission", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Visible labels", "Host validation and submission flow" ], "sourceOfTruth": "Installed Field/control contract", "guide": "references/accessibility.md", "verify": [ "Accessible names and descriptions", "Native values, required and reset", "Invalid focus and disabled/loading behavior" ] }, { "id": "interaction.keyboard", "when": "Changing interactive controls", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Runnable screen", "Installed control keyboard contract" ], "sourceOfTruth": "Installed component behavior and DESIGN.md", "guide": "references/accessibility.md", "verify": [ "Keyboard-only full interaction", "Visible focus in every relevant state", "Select commit/cancel if present" ] }, { "id": "theme.semantic", "when": "Customizing visual roles", "for": [ "designer", "developer", "agent" ], "requires": [ "Installed token manifest", "Actual affected surfaces" ], "sourceOfTruth": "Installed token roles; source tokens.json when developing Flood", "guide": "references/customization.md", "verify": [ "Resolved scoped semantic values", "Text and non-text contrast", "No parallel raw palette" ] }, { "id": "layout.reflow", "when": "Changing layout or type", "for": [ "designer", "reviewer", "agent" ], "requires": [ "Actual composed screen" ], "sourceOfTruth": "DESIGN.md and host content requirements", "guide": "references/composition.md", "verify": [ "320px width", "Root 24px and increased text spacing", "No glyph shrink or unintended page overflow" ] }, { "id": "verification.evidence", "when": "Reporting completion", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Host verification scripts", "Task scope" ], "sourceOfTruth": "Observed command and rendered behavior results", "guide": "references/verification.md", "verify": [ "Commands and actual results recorded", "Manual checks distinguished", "Untested behavior stated" ] }, { "id": "installation.preserve", "when": "Installing or updating guidance", "for": [ "developer", "agent" ], "requires": [ "Existing host instructions", "User scope" ], "sourceOfTruth": "Host files and version-matched guide set", "guide": "references/routing.md", "verify": [ "Existing files preserved", "No linked destinations followed", "No publication inferred from source version" ] }, { "id": "layout.spacing", "when": "Composing or reviewing spacing, density, nested surfaces or moving previews", "for": [ "designer", "developer", "agent" ], "requires": [ "Installed token manifest", "Rendered host and actual wrapper tree" ], "sourceOfTruth": "Installed component recipe and host layout requirements", "guide": "references/spacing.md", "verify": [ "Measure visible gaps and row pitch, including padding and minimum height", "Check wrapping and enlarged text", "Check fine/coarse pointers and nonoverlapping interactive targets", "Preserve keyboard focus and label activation", "Peer form grids sharing an outer frame use coherent tracks and gutters, or have an explicit contextual reason" ] }, { "id": "composition.reuse", "when": "Building or reviewing Flood components, composites, website or host UI", "for": [ "designer", "developer", "reviewer", "agent" ], "requires": [ "Matching installed exports and component contracts", "Existing component anatomy and current composition" ], "sourceOfTruth": "DESIGN.md and the Flood composition skill", "guide": "references/flood-composition/SKILL.md", "verify": [ "Existing semantic primitives remain present in the rendered composition", "Missing reusable capabilities are implemented in a small primitive before the larger composite", "No replacement markup or hidden anatomy used to bypass a primitive", "Alignment checked within each row and in the real host" ] }, { "id": "foundations.roles", "when": "Applying dark surfaces, type, control or icon roles", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Installed semantic roles and actual composited backgrounds", "guide": "references/flood-foundations/SKILL.md", "verify": [ "Trace changed roles to their actual consumers", "Distinguish decoration, necessary boundaries, selection and accent focus", "Check explicit icon sizing, heading semantics, long text and enlarged root geometry" ] }, { "id": "spacing.nesting", "when": "Aligning nested surfaces or controls", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Rendered anatomy, insets, radii and spacing roles", "guide": "references/flood-spacing/SKILL.md", "verify": [ "Measure both axes including line height and minimum height", "Compare nested radius/inset geometry without overriding independent actions", "Check shared siblings and nonoverlapping targets" ] }, { "id": "spacing.preview", "when": "Demonstrating size or feedback transitions", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Component behavior distinguished from preview scene ownership", "guide": "references/flood-spacing/SKILL.md", "verify": [ "Changing size does not resize the preview scene", "Feedback does not move an unrelated sample", "Production controls do not inherit unnecessary fixed demo space" ] }, { "id": "forms.ownership", "when": "Connecting controlled values or native form data", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Installed control values, callbacks and native form contract", "guide": "references/flood-forms/SKILL.md", "verify": [ "Inspect actual FormData and field ownership", "Exercise accepted/refused controlled updates and incomplete drafts", "Defaults match representation; no defaultValue-as-update or invented save guarantee" ] }, { "id": "forms.reset", "when": "Resetting a form or changing value representation", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Installed controlled/uncontrolled, reset and precision contract", "guide": "references/flood-forms/SKILL.md", "verify": [ "Normal and prevented reset preserve documented ownership", "Minute/second defaults match selected precision", "Advisory messages remain valid; native errors and disabled/read-only retain distinct semantics" ] }, { "id": "overlays.ownership", "when": "Opening or nesting a modal or anchored layer", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Installed trigger, open-state, focus and dismissal contract", "guide": "references/flood-overlays/SKILL.md", "verify": [ "One mounted trigger retains props/ref and name", "Topmost Escape and host refusal behave correctly", "Appropriate modal/nonmodal focus and scroll restoration" ] }, { "id": "overlays.geometry", "when": "Placing popups or viewport-edge drawers", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Actual anchor, viewport, scroll container and semantic surface", "guide": "references/flood-overlays/SKILL.md", "verify": [ "Check used sides, viewport edges, resize, long content and RTL", "No drawer gap caused by page scrollbar gutter", "Header, footer and padding leave a useful body reading area at enlarged narrow sizes; fitting rectangles alone is insufficient", "Popup remains distinguishable with no rail-covered or clipped essential content" ] }, { "id": "navigation.intent", "when": "Choosing destinations, selection, panels or disclosure", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Installed navigation, selection and disclosure contract", "guide": "references/flood-navigation/SKILL.md", "verify": [ "Native link behavior and current destination preserved", "Selection, focus and expansion remain distinct", "Long labels and final sidebar items remain usable in actual supported orientations" ] }, { "id": "data.structure", "when": "Presenting records, file items or tables", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Installed semantic primitives and content relationships", "guide": "references/flood-data-display/SKILL.md", "verify": [ "Caption, headers and named-value relationships preserved", "Row actions remain independent named controls", "File metadata/status/progress reuse their existing primitives" ] }, { "id": "data.overflow", "when": "Presenting long, missing or changing content", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Actual data surface and overflow ownership", "guide": "references/flood-data-display/SKILL.md", "verify": [ "Empty/loading/error and absent optional slots exercised", "Final item/cell action and full essential text remain accessible outside rails", "Server/client locale, narrow/enlarged text and RTL checked" ] }, { "id": "feedback.truth", "when": "Reporting operation state or progress", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Actual host operation and installed feedback primitive", "guide": "references/flood-feedback/SKILL.md", "verify": [ "Pending/success/error/cancel/local state is truthful", "Unknown progress never fabricates a percentage", "Empty content explains its cause and appropriate next action" ] }, { "id": "feedback.announcements", "when": "Announcing status, alert or loading transitions", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Installed semantics and required urgency", "guide": "references/flood-feedback/SKILL.md", "verify": [ "One announcement owner rather than duplicate live regions", "Messages do not steal focus merely to announce", "Audible behavior claimed only when tested with actual assistive technology" ] }, { "id": "accessibility.focus", "when": "Reviewing names, keyboard or focus through a task", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Installed component behavior and actual accessibility tree", "guide": "references/flood-accessibility/SKILL.md", "verify": [ "Name, role and state observed rather than inferred visually", "Keyboard completion, reverse navigation, cancel and recovery", "Pointer activation gives custom keyboard owners actual focus across browsers while preserving deliberate host callback focus moves", "Accent focus survives selected/invalid/read-only combinations without layout shift" ] }, { "id": "accessibility.perception", "when": "Reviewing readability under alternate viewing conditions", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Actual text size/weight/background and applicable WCAG criteria", "guide": "references/flood-accessibility/SKILL.md", "verify": [ "Text contrast and supplementary APCA interpretation kept distinct", "Necessary cues are not reclassified as decoration", "Reflow, enlargement, relevant pointer/RTL/forced-color checks and limits reported" ] }, { "id": "verification.applicability", "when": "Stabilizing components or declaring a composition complete", "for": [ "developer", "reviewer", "agent" ], "requires": [ "Matching installed declarations and guide set", "Runnable host and actual content/state requirements" ], "sourceOfTruth": "Current revision, applicable contracts and observed outcomes", "guide": "references/flood-verification/SKILL.md", "verify": [ "Explicit applicable-check disposition for every affected component", "Existing coverage distinguished from checks run for this revision", "Failures, source/host ownership and remaining limits recorded" ] }, { "id": "knowledge.versioned", "when": "Discovering or extending Flood knowledge", "for": [ "developer", "agent" ], "requires": [ "Matching package/configuration/guide versions", "Host instructions" ], "sourceOfTruth": "Installed catalog and selected canonical or customized material", "guide": "references/knowledge.md", "verify": [ "Read scope and version before selecting material", "Finish selected instruction pages", "Run growth and clean-consumer checks for source changes" ] }, { "id": "content.necessary", "when": "Introducing or editing visible interface copy and hierarchy", "for": [ "designer", "developer", "agent" ], "requires": [ "User task and scope", "Existing product vocabulary" ], "sourceOfTruth": "Actual user decisions and current interface context", "guide": "references/flood-interface-content/SKILL.md", "verify": [ "Changed copy has a necessary role or is removed", "Titles, subtitles and hints do not repeat obvious context", "Accessible names, needed constraints and recovery remain available", "Each supporting sentence serves a specific decision or recovery need in the current state, not a hypothetical future risk", "No standing implementation/storage caption merely because the data has a retention limitation", "Prototype provenance stays in README/test handoff unless it changes a current record/choice/action; no automatic permanent environment badge" ] }, { "id": "content.accurate", "when": "Writing state, export, storage or completion messages", "for": [ "designer", "developer", "agent" ], "requires": [ "Actual operation and completed outcome" ], "sourceOfTruth": "Host behavior and confirmed product facts", "guide": "references/flood-interface-content/SKILL.md", "verify": [ "No invented capabilities, expert verification or delivery claims", "Error explains the applicable failure and supported recovery", "Technical details appear only when they affect a user decision" ] }, { "id": "content.reference", "when": "Adapting content from another product or reference", "for": [ "designer", "developer", "agent" ], "requires": [ "Reference purpose", "Host objects, actions and states" ], "sourceOfTruth": "Host capability and user vocabulary", "guide": "references/flood-interface-content/SKILL.md", "verify": [ "Reference pattern is mapped to the host question it answers", "Competitor workflows, promises and marketing language are not transplanted without matching behavior" ] }, { "id": "layout.hierarchy", "when": "Composing or reviewing task titles, group legends, named fields and shared form tracks", "for": [ "designer", "developer", "agent", "reviewer" ], "requires": [ "Installed component and token contracts", "Task reading order and actual rendered host" ], "sourceOfTruth": "Installed hierarchy recipes and host content requirements", "guide": "references/flood-hierarchy/SKILL.md", "verify": [ "Task, group and field roles are distinguishable without redundant headings", "Label is closer to its control than independent fields/groups", "Related rows share measured control edges; width exceptions have a content reason", "Dialog title/body inset is owned once; actions remain reachable at enlarged text", "Calendar content remains readable inside viewport collision limits" ] }, { "id": "records.scan", "when": "Composing record lists, detail views or several row metadata values", "for": [ "designer", "developer", "agent", "reviewer" ], "requires": [ "Current recognition/comparison/action task", "Installed record component contracts", "Rendered sibling records with varied content" ], "sourceOfTruth": "Task information needs and installed record contracts", "guide": "references/flood-records/SKILL.md", "verify": [ "Field to decision and list/detail placement choices recorded outside UI", "Identity and summary remain readable with long and missing metadata", "Stable scan positions or real named comparison columns, not drifting pseudo-columns", "List, details, first-use and filtered empty states reviewed separately" ] }, { "id": "records.meaning", "when": "Presenting category, lifecycle status, priority, timestamps or collection counts", "for": [ "designer", "developer", "agent", "reviewer" ], "requires": [ "Actual field semantics and current user decision" ], "sourceOfTruth": "Host data meanings and corresponding Flood primitive contract", "guide": "references/flood-records/SKILL.md", "verify": [ "Category/state/urgency distinguished with names where needed, not color alone", "Essential triage/comparison fields retained; optional attributes do not compete equally", "Dates identify useful events with suitable precision; formatted equality is not event equality", "Counts and supporting text add current value; necessary announcements remain" ] } ], "guideResolution": "Match guide to source in manifest.files; use its target relative to the host project root." }