fluentui-design 0.1.0

package/skills/fluentui-design/references/maintenance/refresh-and-repin.md

@@ -0,0 +1,68 @@
+# Refresh and Re-Pin
+
+The bundled rules and patterns are pinned to one reviewed baseline. When the
+baseline moves, refresh deliberately instead of editing output by hand.
+
+## When to refresh
+
+- The project installs a `@fluentui/react-components` version other than the
+  baseline named in the entry point.
+- A rule is disputed in review and needs stronger or newer evidence.
+- A new source, such as a design guide or an accessibility standard, is added to
+  the reviewed collection.
+
+## The procedure
+
+1. **Refresh the sources.** Add or update the reviewed sources and their
+   coverage, then validate the evidence pipeline:
+
+   ```
+   npm run validate:sources
+   ```
+
+2. **Re-pin the API facts.** Regenerate the verified allowlist from the sibling
+   API-fact source:
+
+   ```
+   npm run extract-facts
+   npm run check:facts
+   ```
+
+3. **Regenerate the indexes and the mirror.**
+
+   ```
+   npm run generate
+   npm run generate:check
+   ```
+
+4. **Confirm the package.** Validate the rules, the actionability lint, and the
+   references:
+
+   ```
+   npm run validate:rules
+   npm run lint:rules
+   npm run check:refs
+   ```
+
+5. **Run the full gate** before publishing the change:
+
+   ```
+   npm run verify
+   ```
+
+## Rules for the refresh
+
+- Never hand-edit a generated file. The generated marker says so, and the drift
+  gate detects any edit. Delete a stale generated file by regenerating, not by
+  deleting it by hand.
+- Confirm a new export exists before a rule or pattern names it. An unverified
+  name is the most common cause of a failing reference gate.
+- Update the baseline table in the entry point and the pinned commit together,
+  so a reader never sees a mismatch.
+- Record why a rule changed; do not silently adjust a rule to match a newer
+  library.
+
+## Related references
+
+- [Reference index](../index.md) for the decision routes.
+- [Rule index](../rules/index.md) for the rules grouped by area.

package/skills/fluentui-design/references/patterns/PAT-001-application-shell.md

@@ -0,0 +1,77 @@
+---
+id: PAT-001
+title: Application shell
+decisions: [command-scope, navigation-model]
+rules: [RULE-001, RULE-002, RULE-003]
+components: [FluentProvider, Nav, NavItem, NavCategory, NavCategoryItem, NavSubItem, NavDrawer, Breadcrumb, BreadcrumbItem, BreadcrumbButton, BreadcrumbDivider, Toolbar, ToolbarButton, Text, Title1]
+derived: [application-owned app shell composition, application-owned route binding]
+---
+
+# Application shell
+
+## User task
+
+Move between the primary areas of the application and always know where they are, while the
+current page keeps its own heading and commands.
+
+## When to use / when not
+
+Use it for any app with more than one destination. Do not add a shell to a single-screen tool, and
+do not force a shell when the app is embedded inside a host that already owns navigation.
+
+## Region order
+
+1. Banner with product identity and global actions.
+2. Primary navigation (Nav).
+3. Breadcrumb for the current path.
+4. Page heading and page commands.
+5. Main content region.
+
+## Component mapping
+
+Verified exports supply the navigation and command primitives: FluentProvider, Nav and its item
+parts, Breadcrumb, Toolbar, and text roles. The shell itself, the route binding, and the layout
+grid are application-owned compositions, so they are never presented as v9 exports.
+
+## Interaction flow
+
+The router resolves a route, the shell marks the matching Nav item, the Breadcrumb renders the
+path segments, and the routed view renders inside the main region. Clicking a navigation item asks
+the application router to navigate; the component does not change the route on its own.
+
+## State ownership
+
+The application owns the route, the expanded navigation categories, and the narrow-width drawer
+state. Nav selection is derived from the route rather than stored separately.
+
+## Responsive behavior
+
+At the project's narrow breakpoint the navigation column moves into a NavDrawer triggered from the
+banner. The breakpoint is a project convention and must state what it changes at that width.
+
+## Accessibility
+
+The shell provides the banner, navigation, and main landmarks. Exactly one main landmark exists,
+the current destination is marked as current, and a skip link lets keyboard users reach the main
+region directly.
+
+## Edge cases
+
+Loading a route shows a skeleton in the main region while the shell stays usable. An unauthorized
+route renders an explanatory state in the main region without hiding the fact that navigation
+exists. A deep link with unknown segments shows a not-found state inside the shell.
+
+## Rules applied
+
+RULE-001, RULE-002, RULE-003
+
+## Derived decisions
+
+The shell composition, the route binding, and the responsive collapse are application decisions.
+Routing, authorization, and data fetching are not owned by Fluent and are named here as
+application responsibilities.
+
+## Tests
+
+Fixture shell rendering test, landmark structure test, active-route marking test, and a narrow-width
+drawer test.

package/skills/fluentui-design/references/patterns/PAT-002-list-page.md

@@ -0,0 +1,85 @@
+---
+id: PAT-002
+title: Searchable and filterable list page
+decisions: [data-surface, data-processing-location, selection-scope, row-activation, data-resilience, virtualization]
+rules: [RULE-010, RULE-011, RULE-012, RULE-016]
+components: [DataGrid, DataGridBody, DataGridRow, DataGridCell, DataGridHeader, DataGridHeaderCell, DataGridSelectionCell, createTableColumn, Table, TableHeader, TableRow, TableCell, TableBody, TableCellLayout, Input, Button, MenuButton, Menu, MenuTrigger, MenuPopover, MenuList, MenuItem, Spinner, Skeleton, SkeletonItem, MessageBar, MessageBarBody, Checkbox, Field]
+derived: [application-owned FilterBar composition, application-owned query and pagination state]
+---
+
+# Searchable and filterable list page
+
+## User task
+
+Find a set of records, narrow them down, act on one or on many, and understand what the current
+result set contains.
+
+## When to use / when not
+
+Use it when the user works with a collection of similar records. Use a simple Table when the data is
+static and needs no filtering, selection, or sorting. Do not use a grid when the task is really a
+narrative detail view.
+
+## Region order
+
+1. Page heading and one primary action.
+2. Filter and search controls.
+3. Result count and, when server-paged, a pager.
+4. The grid or table.
+5. Bulk-action bar, shown only while rows are selected.
+
+## Component mapping
+
+DataGrid and its parts provide the controlled, keyboard-navigable surface; Table and its parts
+provide native table semantics for simpler cases. Input, Menu, Button, Checkbox, Spinner, Skeleton,
+and MessageBar are verified exports. The FilterBar, the query state, and the pager are
+application-owned compositions.
+
+## Interaction flow
+
+Typing in search or changing a filter updates application query state. In server mode this issues a
+request and shows a pending state in the grid region. Clicking a row opens the record when the row
+is the activation target; when a cell contains its own action control, that control handles its own
+click and does not also activate the row. Selecting rows reveals the bulk-action bar.
+
+## State ownership
+
+The application owns the query, page, sort, filter, and selected ids. Whether operations run locally
+or on the server is explicit in application state, not inferred by the grid.
+
+## Responsive behavior
+
+Below the project's narrow breakpoint, low-priority columns are hidden behind a detail view and
+filters collapse into a single control that opens a panel. The grid keeps vertical scrolling; it
+never requires two-dimensional scrolling to read a value. Virtualize the grid only after measuring a
+performance need, because virtualization keeps only the visible rows in the DOM and can break
+in-page search and predictable focus movement.
+
+## Accessibility
+
+The grid uses one tab stop with arrow-key navigation inside it. Sort state is announced, selection
+changes are announced, and an async result update is announced through a polite status region. The
+select-all control states whether it selects the current page or all matching results.
+
+## Edge cases
+
+Loading shows Skeletons in the grid region. No data, no search matches, and a failed load each show a
+distinct message; the failed state offers a retry action. A server-paged sort re-queries instead of
+sorting only the loaded page. A selection that spans pages keeps its ids when the page changes. When
+virtualization is enabled, keep a stable row key, expose the row's position and total count to
+assistive technology, and ensure focus is not lost when the visible window moves.
+
+## Rules applied
+
+RULE-010, RULE-011, RULE-012, RULE-016
+
+## Derived decisions
+
+The FilterBar composition, the explicit local-versus-server choice, and the activation-versus-
+selection split are application decisions. Data fetching, sorting, filtering, and pagination are
+application responsibilities; the grid only renders and reports interaction.
+
+## Tests
+
+Fixture list rendering test, keyboard grid navigation test, sort-issues-request test, selection-scope
+test, and the four-state (loading, empty, search-empty, error) test.

package/skills/fluentui-design/references/patterns/PAT-003-record-detail.md

@@ -0,0 +1,74 @@
+---
+id: PAT-003
+title: Record detail page
+decisions: [permission-state]
+rules: [RULE-003, RULE-029]
+components: [Card, CardHeader, CardFooter, TabList, Tab, Text, Title1, Subtitle1, Divider, Badge, MessageBar, MessageBarBody, Button, Link]
+derived: [application-owned PageHeader composition, application-owned related-records loader]
+---
+
+# Record detail page
+
+## User task
+
+Understand one record at a glance, read its details, and reach the actions and related information
+that belong to it.
+
+## When to use / when not
+
+Use it for a single addressable record with related data. Do not use it when the user needs to
+compare many records, which is the list page's job.
+
+## Region order
+
+1. Page heading naming the record, with status and one primary action.
+2. Summary cards for the most important facts.
+3. Peer views (overview, related, history) as tabs.
+4. Destructive or secondary actions, separated from the primary action.
+
+## Component mapping
+
+Card and its parts, TabList and Tab, Badge, Divider, Button, Link, and text roles are verified
+exports. The PageHeader grouping and the related-records loader are application-owned compositions.
+Routing, authorization, and fetching are application responsibilities.
+
+## Interaction flow
+
+The route identifies the record; the application loads it and renders the heading. Switching a tab
+changes only the tab region. A read-only viewer sees the same structure with action controls omitted
+and a visible explanation of the restricted state, rather than an empty page.
+
+## State ownership
+
+The application owns the loaded record, the selected tab, and the permission result. Card and tab
+components hold only presentational state such as hover or the selected tab index.
+
+## Responsive behavior
+
+Summary cards stack to one column below the project's narrow breakpoint. Tabs overflow into a menu
+rather than scrolling out of reach. Related tables inside a tab follow the list page rules.
+
+## Accessibility
+
+The record name is the single top-level heading. Tabs follow the tablist keyboard model with the
+selected tab associated with its panel. A restricted or read-only state is announced and explained
+in text, and the current status is not conveyed by color alone.
+
+## Edge cases
+
+A missing record renders a not-found state with a path back to the list. A record the user may not
+view shows a permission explanation without revealing whether hidden fields exist. A partially
+failed related-data load shows an inline error in that tab only.
+
+## Rules applied
+
+RULE-003, RULE-029
+
+## Derived decisions
+
+The PageHeader composition and the choice of tabs for peer views are application decisions.
+Authorization and related-data fetching are named here as application responsibilities.
+
+## Tests
+
+Fixture detail rendering test, tab keyboard test, read-only-state test, and a missing-record test.

package/skills/fluentui-design/references/patterns/PAT-004-form-page.md

@@ -0,0 +1,78 @@
+---
+id: PAT-004
+title: Create and edit form page
+decisions: [form-layout, field-annotation, submit-feedback]
+rules: [RULE-005, RULE-006, RULE-007, RULE-029, RULE-030]
+components: [Field, Input, Textarea, Select, Combobox, Dropdown, Option, Checkbox, Radio, RadioGroup, Switch, Slider, Label, Button, MessageBar, MessageBarBody, Spinner]
+derived: [application-owned FormSection grouping, application-owned validation schema]
+---
+
+# Create and edit form page
+
+## User task
+
+Enter or change a set of related values, understand any problems with them, and submit the result
+with confidence.
+
+## When to use / when not
+
+Use it when the task is to create or edit a defined object with several fields. Do not use a full
+page for editing one or two fields in the context of a list; use the contextual-edit pattern.
+
+## Region order
+
+1. Page heading naming the object, with one primary submit action.
+2. Grouped field sections, each introduced by a heading.
+3. Submission feedback near the action.
+4. Cancel, kept visually secondary.
+
+## Component mapping
+
+Field, Input, Textarea, Select, Combobox, Dropdown, Option, Checkbox, Radio, RadioGroup, Switch,
+Slider, Label, Button, MessageBar, and Spinner are verified exports. The FormSection grouping and
+the validation schema are application-owned. Validation, persistence, and authorization are
+application responsibilities.
+
+## Interaction flow
+
+The user moves through fields in one reading order. A field reports its error after blur or on
+submit, never before it has been touched. On submit the action becomes disabled and shows a pending
+state. Success navigates to the saved record; failure keeps the entered values and shows an error
+summary near the action plus field-level messages.
+
+## State ownership
+
+The application owns the draft value, touched and dirty state, the validation result, and the
+submission status. Field components render the value and message they are given.
+
+## Responsive behavior
+
+The form is single-column by default and survives narrow widths without changing reading order.
+Short related pairs may share a row above the project's narrow breakpoint only.
+
+## Accessibility
+
+Every control has a programmatic label and, where needed, help text tied to the control. The error
+summary is announced on submit, and focus moves to the summary or the first invalid field. The
+pending submit action keeps an accessible name.
+
+## Edge cases
+
+Server-side validation errors map onto their fields and are also summarized. A duplicate submission
+is prevented while a request is pending. Leaving the page with unsaved changes triggers a
+confirmation. A field whose value arrives after load shows a pending state rather than an empty
+value.
+
+## Rules applied
+
+RULE-005, RULE-006, RULE-007, RULE-029, RULE-030
+
+## Derived decisions
+
+The FormSection grouping, the single-column default, and the blur-first validation timing are
+application decisions. Server-side validation is mandatory; client-side validation is advisory only.
+
+## Tests
+
+Fixture form rendering test, no-early-error test, duplicate-submit test, server-error mapping test,
+and an unsaved-change guard test.

package/skills/fluentui-design/references/patterns/PAT-005-contextual-edit.md

@@ -0,0 +1,75 @@
+---
+id: PAT-005
+title: Short contextual edit in a drawer or focused dialog
+decisions: [edit-surface, modal-behavior]
+rules: [RULE-008, RULE-009, RULE-029]
+components: [Drawer, DrawerBody, DrawerHeader, DrawerHeaderTitle, DrawerFooter, Dialog, DialogTrigger, DialogSurface, DialogBody, DialogTitle, DialogContent, DialogActions, Button, Field, Input]
+derived: [application-owned edit-surface selector, application-owned dirty-state guard]
+---
+
+# Short contextual edit in a drawer or focused dialog
+
+## User task
+
+Change a small amount of information without leaving the page they are working on.
+
+## When to use / when not
+
+Use a dialog for a short, bounded decision or a two-field edit that benefits from full attention.
+Use a drawer for a slightly larger contextual edit that should keep the underlying list or record
+visible. Do not use either for a long multi-section form; that belongs on the form page.
+
+## Region order
+
+1. Surface title naming the object being edited.
+2. Editable fields.
+3. Primary save action and a secondary cancel action.
+4. Confirmation when the surface closes with unsaved changes.
+
+## Component mapping
+
+Drawer and its parts, Dialog and its parts, Button, Field, and Input are verified exports. The rule
+that selects between drawer and dialog, the dirty-state guard, and the save call are application-
+owned. Fetching the edited record and persisting the change are application responsibilities.
+
+## Interaction flow
+
+A trigger control opens the surface with the current values. The user edits fields; the primary
+action saves and closes on success. Attempting to dismiss with unsaved changes opens a confirmation
+with Keep editing and Discard. On close, focus returns to the control that opened the surface.
+
+## State ownership
+
+The application owns open state, the draft value, dirty state, and the pending save. The surface
+owns only local presentation such as open animation.
+
+## Responsive behavior
+
+At the project's narrow breakpoint a drawer may occupy the full width and a dialog fits the viewport
+with scrolling content. Neither may push its action buttons out of reach.
+
+## Accessibility
+
+Each surface has a title, traps focus while open, and returns focus to its trigger on close. The
+confirmation is itself a dialog with a title. Escape closes the surface only when the dismissal will
+not silently lose work.
+
+## Edge cases
+
+A save failure keeps the surface open, preserves the draft, and shows the error inside the surface.
+A record deleted in another session is reported on save rather than overwriting. A very small
+viewport keeps the primary action reachable and the content scrollable.
+
+## Rules applied
+
+RULE-008, RULE-009, RULE-029
+
+## Derived decisions
+
+The drawer-versus-dialog choice and the dirty-state guard are application decisions. Persistence and
+fetching are application responsibilities. Server-side validation is mandatory; client-side
+validation is advisory only.
+
+## Tests
+
+Fixture drawer open/close test, return-focus test, dirty-guard test, and a save-failure test.

package/skills/fluentui-design/references/patterns/PAT-006-settings-page.md

@@ -0,0 +1,78 @@
+---
+id: PAT-006
+title: Settings page with optional advanced sections
+decisions: [progressive-disclosure, navigation-model]
+rules: [RULE-013, RULE-014]
+components: [Accordion, AccordionItem, AccordionHeader, AccordionPanel, Switch, RadioGroup, Radio, Select, Dropdown, Option, Button, Field, TabList, Tab]
+derived: [application-owned settings model, application-owned persistence adapter]
+---
+
+# Settings page with optional advanced sections
+
+## User task
+
+Review and change configuration for a product or a record, where most values are simple and a few
+are advanced.
+
+## When to use / when not
+
+Use it when settings fall into a few peer groups with occasional advanced options. Do not hide
+required values inside collapsed sections, and do not use this pattern for an ordered setup task,
+which is the multi-step pattern.
+
+## Region order
+
+1. Page heading naming the scope of the settings.
+2. Either peer tabs or a single scrolling page of sections.
+3. Simple settings first.
+4. Advanced sections, collapsed by default.
+5. Save or apply action.
+
+## Component mapping
+
+Accordion and its parts, Switch, RadioGroup and Radio, Select, Dropdown, Option, TabList, Tab, Button,
+and Field are verified exports. The settings model and the persistence adapter are application-owned.
+Loading and saving settings are application responsibilities.
+
+## Interaction flow
+
+The user changes a value and either saves explicitly or receives an immediate effect, depending on
+the setting. Advanced sections expand on demand. A validation error inside a collapsed section
+expands that section and moves focus to the field so the error is never hidden.
+
+## State ownership
+
+The application owns the settings model, which values are dirty, and whether a save is pending. The
+accordion owns only which sections are expanded.
+
+## Responsive behavior
+
+Advanced sections behave the same at every width. Where tabs are used, overflow tabs move into a menu
+at narrow widths rather than scrolling away.
+
+## Accessibility
+
+Accordion headers expose their expanded state and are operable by keyboard. Dependent values are
+grouped so their relationship is announced. No required setting is reachable only through a
+collapsed region.
+
+## Edge cases
+
+A settings load failure shows an error with retry rather than rendering empty controls. A save
+failure keeps the edited values and reports the problem. A permission-restricted section is shown
+with an explanation rather than silently omitted.
+
+## Rules applied
+
+RULE-013, RULE-014
+
+## Derived decisions
+
+Whether a setting applies immediately or on save, and how advanced sections are grouped, are
+application decisions. Persistence is an application responsibility. Server-side validation is
+mandatory; client-side validation is advisory only.
+
+## Tests
+
+Fixture settings rendering test, collapsed-validation-error test, and a tabs-or-sections keyboard
+test.

package/skills/fluentui-design/references/patterns/PAT-007-multi-step-task.md

@@ -0,0 +1,79 @@
+---
+id: PAT-007
+title: Multi-step task with review and preserved state
+decisions: [save-model, submit-feedback]
+rules: [RULE-029, RULE-030]
+components: [Button, Field, Input, Textarea, Dialog, DialogTrigger, DialogSurface, DialogBody, DialogTitle, DialogContent, DialogActions, MessageBar, MessageBarBody, Spinner, Divider]
+derived: [application-owned step machine, application-owned draft persistence]
+---
+
+# Multi-step task with review and preserved state
+
+## User task
+
+Complete a task that spans several steps, be able to go back, and submit the whole result once at
+the end.
+
+## When to use / when not
+
+Use it when a task is genuinely ordered and too large for one screen, such as onboarding or a
+guided setup. Do not split a short form into steps, and do not use this pattern when the steps are
+independent, which the settings pattern covers.
+
+## Region order
+
+1. Step indicator showing position and total.
+2. Current step heading and fields.
+3. Back and Continue actions, with the primary action last.
+4. A review step summarizing all entered values.
+5. Final submit action.
+
+## Component mapping
+
+Button, Field, Input, Textarea, Dialog and its parts, MessageBar, MessageBarBody, Spinner, and
+Divider are verified exports. The step machine, the draft persistence, and the review summary are
+application-owned. Persistence and the final submit are application responsibilities.
+
+## Interaction flow
+
+Moving forward validates only the current step. Moving back preserves entered values without
+revalidating. The review step lets the user jump back to a step by name. Final submit disables its
+action, shows a pending state, and prevents a duplicate submission.
+
+## State ownership
+
+The application owns the step index, the accumulated draft, per-step validation, and the final
+submission status. The draft must survive back navigation and, where the product requires it, a
+reload.
+
+## Responsive behavior
+
+The step indicator becomes compact at narrow widths but still shows position and total. Actions wrap
+to a stable row rather than scrolling off screen.
+
+## Accessibility
+
+The current step is announced when it changes and focus moves to the step heading. The step
+indicator is not the only way to learn position; the heading states it in text. Submit progress is
+announced without moving focus.
+
+## Edge cases
+
+Leaving the task with unsaved progress triggers a confirmation. A failed step validation keeps the
+user on that step with field messages. A submit failure keeps all steps intact and offers retry.
+Refreshing mid-task restores the draft when persistence is enabled.
+
+## Rules applied
+
+RULE-029, RULE-030
+
+## Derived decisions
+
+The step machine, the choice to validate per step, and the decision to persist a draft are
+application decisions. Persistence and authorization are application responsibilities. Server-side
+validation is mandatory; client-side validation is advisory only.
+
+## Tests
+
+Fixture step navigation test, back-preserves-values test, duplicate-submit test, and a review-jump
+test.