fluentui-design 0.1.0

package/skills/fluentui-design/references/patterns/PAT-008-dashboard.md

@@ -0,0 +1,78 @@
+---
+id: PAT-008
+title: Dashboard whose content reflects actual tasks and data
+decisions: [feedback-channel, data-resilience, permission-state]
+rules: [RULE-003, RULE-015, RULE-016]
+components: [Card, CardHeader, CardFooter, Text, Title1, Subtitle1, MessageBar, MessageBarBody, Spinner, Skeleton, SkeletonItem, Badge, Button, ProgressBar]
+derived: [application-owned dashboard composition, application-owned data aggregation]
+---
+
+# Dashboard whose content reflects actual tasks and data
+
+## User task
+
+See the state of the things they care about and decide what to do next.
+
+## When to use / when not
+
+Use it when several small summaries help the user choose a next action. Do not use a dashboard as
+decoration; every tile must reflect real data and lead somewhere or state a status. Do not use it
+when the user only needs one focused task.
+
+## Region order
+
+1. Page heading naming the scope, such as the current team or workspace.
+2. A durable status message when something needs attention.
+3. Summary tiles, ordered by importance.
+4. A recent-activity or task list.
+5. A persistent link to the full list behind each tile.
+
+## Component mapping
+
+Card and its parts, Badge, ProgressBar, Button, MessageBar, MessageBarBody, Spinner, Skeleton,
+SkeletonItem, and text roles are verified exports. The dashboard composition, the tile ordering, and
+the data aggregation are application-owned. Fetching and authorization are application
+responsibilities.
+
+## Interaction flow
+
+Each tile loads its own data and shows a skeleton until it settles. A tile that fails shows an inline
+error with retry and does not blank the whole dashboard. Selecting a tile navigates to the relevant
+filtered list. A transient confirmation uses a toast; a condition the user must re-read uses a
+MessageBar that persists.
+
+## State ownership
+
+The application owns each tile's data, loading, and error state, plus the permission scope of the
+page. Tiles hold no shared state with one another so one failure stays local.
+
+## Responsive behavior
+
+Tiles stack to one column below the project's narrow breakpoint. Tile content keeps its explanation
+and action; it never truncates a status into an unlabeled badge.
+
+## Accessibility
+
+Each tile has a heading so it appears in the document outline. Status conveyed by color is paired with
+text. Loading and error states are announced, and the dashboard provides a logical heading order from
+the page heading down to tile headings.
+
+## Edge cases
+
+A permission-restricted dashboard shows an explanatory state instead of empty tiles. A tile with no
+data shows a distinct empty state, not a zero value that looks like real data. A slow tile does not
+block the others, and a stale tile shows when it was last updated.
+
+## Rules applied
+
+RULE-003, RULE-015, RULE-016
+
+## Derived decisions
+
+The tile set, the importance ordering, and per-tile loading are application decisions. Data fetching
+and authorization are application responsibilities.
+
+## Tests
+
+Fixture dashboard rendering test, per-tile loading and error tests, heading-order test, and a
+permission-state test.

package/skills/fluentui-design/references/rules/index.md

@@ -0,0 +1,97 @@
+<!-- GENERATED FILE — DO NOT EDIT; source: rules/rules.json -->
+
+# Rule Index
+
+Rules grouped by decision area. Each rule is operational: it states what to do,
+when it applies, and where its evidence comes from. Full provenance lives in
+`rules/rules.json`.
+
+## app-shell
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-001 | should | Compose the whole application inside a FluentProvider and build the shell navigation yourself from Nav, Toolbar, and layout primitives, because v9 exports no shell component. |
+| RULE-002 | should | Render the primary destinations with Nav and its item parts, and render the current position with Breadcrumb, because routing itself stays application-owned. |
+
+## page-chrome
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-003 | must | Place a single top-level heading that names the screen's task at the start of the content region, and use lower heading levels only for structure beneath it. |
+| RULE-004 | should | Reserve one visually primary action for the screen and place additional page commands in a Toolbar, moving overflow actions into a menu. |
+
+## composition
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-026 | must | Wrap the application in a single FluentProvider that sets the theme and text direction, and let nested providers be exceptions rather than the rule. |
+| RULE-027 | must | Own routing, data fetching, authorization, and persistence in application code, and use Fluent components only for presentation and local interaction state. |
+| RULE-028 | should | Style Fluent components with makeStyles and compose their public slots, rather than depending on internal class names or undocumented DOM structure. |
+
+## task-flows
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-029 | must | Track dirty state and confirm before discarding unsaved changes when the user closes, navigates away from, or switches context in the editor. |
+| RULE-030 | must | Disable the submit action while a request is pending, show progress in place, and re-enable the action when the request settles. |
+
+## forms
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-005 | must | Wrap each control in a Field that provides a visible label, and place help or error text through the Field's message slot rather than beside it. |
+| RULE-006 | should | Show a field error after the user leaves the field or submits the form, and never before the user has entered a value, so the form does not scold an untouched field. |
+| RULE-007 | should | Lay fields out in one column by default and group related fields under a shared heading, because a single reading path is easier to follow and to complete. |
+
+## data-grid
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-010 | should | Use DataGrid when the layout must be controlled by column definitions and keyboard grid behavior is required, and use Table when a native table structure is the goal. |
+| RULE-011 | should | Decide explicitly whether each collection operation runs on loaded rows or on the server, and pass the resulting state into the grid so the component does not imply a data source it does not have. |
+| RULE-012 | must | Make the selection scope explicit to the user, and when a bulk action can apply to all matching results rather than only the loaded page, offer that choice deliberately. |
+
+## overlays
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-008 | should | Place a short, self-contained decision in a Dialog with a title and explicit action buttons, so the interaction stays bounded and easy to dismiss. |
+| RULE-009 | should | Use a Drawer for a contextual edit that keeps the underlying context visible, and confirm before discarding unsaved changes when the drawer closes. |
+
+## disclosure
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-013 | must | Keep fields that the task requires visible or clearly summarized, and reserve collapsed sections for genuinely optional or advanced content. |
+| RULE-014 | should | Use TabList to switch between peer views of the same record, and keep sequential task steps out of tabs so users are not misled about order. |
+
+## feedback
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-015 | should | Place conditions the user must be able to read later in a MessageBar, and place short-lived confirmations in a Toast, because the two differ in persistence and urgency. |
+| RULE-016 | must | Provide a distinct state for loading, for genuinely empty data, for an empty search result, and for a failed load, so the user can tell the difference and knows what to do next. |
+
+## responsive
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-023 | must | Let content reflow into a single column and scroll vertically so nothing is lost, rather than clipping or forcing two-dimensional scrolling. |
+| RULE-024 | should | Express margins, padding, and alignment with logical properties and set the provider direction, so the layout mirrors without a separate stylesheet. |
+| RULE-025 | should | Let long values wrap where space allows and truncate with an accessible full value where it does not, so hidden text stays available. |
+
+## accessibility
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-020 | must | Preserve a visible focus indicator on every interactive element and ensure sticky or overlaying regions never cover the focused control. |
+| RULE-021 | must | Give composite widgets a single tab stop and arrow-key movement within it, and ensure nested action controls are reachable without conflicting with row activation. |
+| RULE-022 | must | Give every meaningful icon or color-coded control a programmatic name and an instruction where needed, and hide purely decorative icons from assistive technology. |
+
+## theming
+
+| Rule | Strength | Instruction |
+| --- | --- | --- |
+| RULE-017 | must | Reference Fluent tokens through makeStyles instead of hard-coding colors, spacing, or font values, so a theme change flows through the whole app. |
+| RULE-018 | should | Assign text a role from the Fluent type ramp and let the role determine size, weight, and line height, rather than setting font sizes per screen. |
+| RULE-019 | must | Honor the user's reduced-motion preference and keep transitions short and purposeful, because motion that cannot be suppressed can cause discomfort. |