fluentui-design 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to the `fluentui-design` skill are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the skill uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Each release records three things: the skill version, the baseline
+`@fluentui/react-components` package version, and the pinned `fluentui-mcp` facts commit. See
+[MAINTENANCE.md](MAINTENANCE.md) for the re-pin procedure.
+
+## [0.1.0] - 2026-09-20
+
+### Baseline
+
+| Item | Value |
+| --- | --- |
+| `@fluentui/react-components` | 9.74.7 |
+| React peer range | `>=16.14.0 <20.0.0` |
+| `fluentui-mcp` facts commit | d595d79 |
+
+### Added
+
+- Sourced evidence pipeline: a 45-entry source catalog (`SRC-001`..`SRC-045`), an analyzed coverage
+  matrix, and a findings/conflicts record.
+- Rules catalog with 30 stable rules (`RULE-001`..`RULE-030`), each traced to its evidence.
+- Eight application patterns (`PAT-001`..`PAT-008`) with decision routes and a generated reference
+  index.
+- The `fluentui-design` skill package (`SKILL.md` plus `references/`), mirrored byte-for-byte to
+  `.agents/skills/fluentui-design/`.
+- Verification tooling: example snippets are type-checked but never executed, secrets are scanned,
+  freshness is pinned, and generated output is drift-checked.
+- A runnable Vite + React fixture application with Playwright and axe coverage of the list, editor,
+  overlays, states, theming, and narrow viewports.
+- An evaluation set: 12 fixed tasks, a 7-dimension rubric, and deterministic recorded results, with
+  a reproduction gate (`npm run check:evaluation`).
+
+### Replaced guidance history
+
+No guidance has been replaced in the initial release, so this section is empty. It exists now so
+that later replacements are appended here rather than edited into history.
+
+When guidance is superseded, add one entry per replaced item in this shape:
+
+```
+- RULE-0XX: <what changed>. Reason: <why>. Superseded by: RULE-0YY.
+```
+
+The replaced rule keeps its id, and the successor lists it in the successor's `supersedes` array.
+The old rule's text also gains a "Superseded by `RULE-0YY`" sentence, so the forward pointer is
+visible. Ids are never reused or renumbered. See [MAINTENANCE.md](MAINTENANCE.md) section 6.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blendsdk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# Fluent UI Design Skill
+
+An evidence-backed Agent Skill that helps a coding agent design, implement, and review coherent
+standalone web applications with **Fluent UI React v9**. It focuses on *application composition*:
+which surface to use, where it belongs, and how the parts work together — not on repeated component
+API recall.
+
+## Scope
+
+The skill answers composition questions:
+
+- Choosing a surface: a page, a drawer, a dialog, or an inline editor.
+- Arranging navigation, page chrome, commands, and content regions.
+- Deciding state ownership, the save model, and how submission reports back.
+- Laying out forms, data grids, tabs, and multi-step task flows.
+- Reviewing accessibility, responsive behavior, and visual coherence.
+
+It does **not** restate component props, imports, or slots. Every rule and pattern is derived from a
+reviewed set of sources and cites the evidence it came from.
+
+## Division of labor with the sibling `fluentui` skill
+
+This project is deliberately complementary to the API-focused `fluentui` skill produced by the
+sibling `fluentui-mcp` repository.
+
+| Skill | Owns | Use it for |
+| --- | --- | --- |
+| `fluentui-design` (this project) | Composition rules and patterns, with sourced design evidence | "Where should this go, and how should the parts work together?" |
+| `fluentui` (sibling) | Pinned API facts: exact props, types, imports, slots | "What is the exact prop or import for this component?" |
+
+The two skills are meant to be co-installed. `fluentui-design` links to `fluentui` for API facts
+instead of copying them, so API drift cannot silently desynchronize the two.
+
+## Install
+
+Install the skill into the agent clients detected on your machine with one command:
+
+```
+npx -y fluentui-design skill install
+```
+
+The installer copies the bundled skill into each detected client's skill directory. Use the options
+below to change what it targets:
+
+| Option | Purpose |
+| --- | --- |
+| `--all` | Install into every detected client instead of asking. |
+| `--target <dir>` | Install into a specific skill directory; repeat the flag for more than one. |
+| `--project` | Prefer the current project's skill directory over the global one. |
+| `--link` | Symlink the bundled skill instead of copying it. |
+| `--dry-run` | Report what would change without writing anything. |
+
+Inspect or remove an installation with the `status` and `uninstall` subcommands:
+
+```
+npx -y fluentui-design skill status
+npx -y fluentui-design skill uninstall --target <dir>
+```
+
+## Usage
+
+The skill is authored under [`skill/`](skill/SKILL.md) and mirrored byte-for-byte to
+[`.agents/skills/fluentui-design/`](.agents/skills/fluentui-design/SKILL.md). Install it the way an
+agent discovers skills:
+
+1. Copy `.agents/skills/fluentui-design/` into your agent's skill directory, or point the agent at
+   this repository's `.agents/skills/` folder.
+2. Install the sibling `fluentui` skill from `fluentui-mcp` next to it.
+3. Start from [`skill/SKILL.md`](skill/SKILL.md). It routes each task to the pattern or reference
+   that resolves the decision.
+
+The entry point lists the skill's triggers and non-triggers, and the generated
+[reference index](skill/references/index.md) maps every decision to the patterns and rules that
+resolve it.
+
+## Version baseline
+
+The bundled facts are pinned to one reviewed baseline. Update the table below deliberately (see
+[MAINTENANCE.md](MAINTENANCE.md)); never edit generated output by hand.
+
+| Item | Value |
+| --- | --- |
+| UI library | `@fluentui/react-components` **9.74.7** |
+| React peer range | `>=16.14.0 <20.0.0` |
+| API-fact source | `fluentui-mcp` enhanced schema pinned at commit **d595d79** |
+
+If an application uses a different package version, the skill tells the agent to say so and
+re-verify the rules it uses.
+
+## Repository layout
+
+| Path | Contents |
+| --- | --- |
+| `skill/` | The authored skill (`SKILL.md` + `references/`), mirrored to `.agents/skills/`. |
+| `sources/`, `rules/`, `research/`, `facts/` | Source catalog, rules catalog, and analysis artifacts. |
+| `scripts/` | Validators, generator, gates, and their tests. |
+| `fixture/` | A Vite + React application that demonstrates one coherent composition, with Playwright + axe tests. |
+| `evaluation/` | Fixed tasks, a rubric, and recorded deterministic evidence. |
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `npm run verify` | Full check: typecheck, lint, unit tests, catalog and skill gates, then Playwright + axe. |
+| `npm run verify:static` | The browser-free subset; fast inner loop. |
+| `npm run test` | Unit tests under `scripts/__tests__/`. |
+| `npm run test:e2e` | Playwright tests under `fixture/e2e/`. |
+
+## Known limitations
+
+- **No model-provider evaluation.** Agent-answer quality and the skill-versus-baseline comparison in
+  [`evaluation/results.md`](evaluation/results.md) are marked `untested`. The recorded evidence is
+  deterministic: committed artifacts, gates, and accessibility findings, not generated answers.
+- **Design assets are not fully analyzed.** The official Figma kits and Teams UI templates
+  (`SRC-045`) are recorded as a discovered expansion target; `SRC-002` covers only the public
+  getting-started page. Rules therefore lean on published guidance and the component library, not on
+  Figma files.
+- **The dedicated v9 DataGrid usage page was not analyzed.** Grid rules lean on the accessibility
+  practices guide (APG) and the pinned package source (`SRC-027`).
+- **Automated accessibility output is findings, not conformance.** The fixture is scanned with axe
+  and the results are reported as defects that were fixed; the project makes no WCAG conformance
+  claim.
+
+## Maintenance
+
+[MAINTENANCE.md](MAINTENANCE.md) documents how to recheck sources, detect redirects and content
+changes, re-pin the baseline, find the rules affected by a fact change, rerun the fixture, and retain
+a history of replaced guidance. [CHANGELOG.md](CHANGELOG.md) records each skill version with its
+baseline. [COMPLETION-REPORT.md](COMPLETION-REPORT.md) closes the initial build honestly.

package/dist/bin.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * The `fluentui-design` command-line entry point.
+ *
+ * Only one command group is exposed today: `fluentui-design skill …`, which
+ * installs, inspects, and removes the Fluent UI design Agent Skill. The
+ * dispatcher keeps the top-level surface small so future command groups can be
+ * added without changing the skill installer.
+ *
+ * @module bin
+ */
+/**
+ * Runs the dispatcher for a full argument list.
+ *
+ * @param argv - Arguments after the `fluentui-design` program name.
+ * @returns Process exit code.
+ */
+export declare function main(argv: string[]): Promise<number>;

package/dist/bin.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * The `fluentui-design` command-line entry point.
+ *
+ * Only one command group is exposed today: `fluentui-design skill …`, which
+ * installs, inspects, and removes the Fluent UI design Agent Skill. The
+ * dispatcher keeps the top-level surface small so future command groups can be
+ * added without changing the skill installer.
+ *
+ * @module bin
+ */
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { main as runSkillCommand } from "./skill/install-skill.js";
+/** Prints the top-level help text. */
+function printUsage() {
+    console.log(`The Fluent UI design Agent Skill command-line tool.
+
+Usage:
+  fluentui-design skill install [options]     Install or update the skill
+  fluentui-design skill status [options]      Show the installed version
+  fluentui-design skill uninstall [options]   Remove the installed skill
+  fluentui-design --help                      Show this help
+
+Run 'fluentui-design skill --help' for the installer options.`);
+}
+/**
+ * Runs the dispatcher for a full argument list.
+ *
+ * @param argv - Arguments after the `fluentui-design` program name.
+ * @returns Process exit code.
+ */
+export async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "-h" || command === "--help") {
+        printUsage();
+        return 0;
+    }
+    if (command === "skill") {
+        return runSkillCommand(rest);
+    }
+    console.error(`error: unknown command '${command}'`);
+    printUsage();
+    return 2;
+}
+/**
+ * True when this module is the process entry point, resolving symlinks so the
+ * guard also works through npm's `.bin` shims.
+ *
+ * @returns True when this file is the entry point.
+ */
+function isEntryPoint() {
+    if (!process.argv[1]) {
+        return false;
+    }
+    try {
+        return fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntryPoint()) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    }, (error) => {
+        console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,IAAI,IAAI,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEnE,sCAAsC;AACtC,SAAS,UAAU;IACjB,OAAO,CAAC,GAAG,CAAC;;;;;;;;8DAQgD,CAAC,CAAC;AAChE,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAc;IACvC,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAEhC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACtE,UAAU,EAAE,CAAC;QACb,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACxB,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,2BAA2B,OAAO,GAAG,CAAC,CAAC;IACrD,UAAU,EAAE,CAAC;IACb,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY;IACnB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,IAAI,YAAY,EAAE,EAAE,CAAC;IACnB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC9B,CAAC,IAAI,EAAE,EAAE;QACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC1B,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;QACjB,OAAO,CAAC,KAAK,CAAC,UAAU,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/skill/install-skill.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Install and update the Fluent UI design Agent Skill into coding agents.
+ *
+ * The skill ships inside the `fluentui-design` package at
+ * `skills/fluentui-design/`. This installer copies it into the skill
+ * directories of the supported clients (OpenCode, Claude Code, Codex, and the
+ * shared `.agents/skills` convention), globally or per project. It replaces
+ * only the namespaced `fluentui-design/` directory and never touches any other
+ * skill.
+ *
+ * @module skill/install-skill
+ */
+/** The skill directory name installed into every client. */
+export declare const SKILL_DIR_NAME = "fluentui-design";
+/** The marker file written inside an installed skill directory. */
+export declare const MARKER_FILE = ".fluentui-design-skill.json";
+/** The value recorded in the marker's `source` field. */
+export declare const SOURCE_NAME = "fluentui-design";
+/** Prefix of the temporary sibling directory used during an atomic install. */
+export declare const TEMP_PREFIX = ".fluentui-design-skill.tmp-";
+/** Prefix of the backup directory kept while an install is in flight. */
+export declare const BACKUP_PREFIX = ".fluentui-design-skill.bak-";
+/**
+ * The shape of the marker file written into an installed skill directory.
+ */
+export interface SkillMarker {
+    /** The package version that was installed. */
+    version: string;
+    /** Fixed provenance string identifying the installer. */
+    source: string;
+    /** ISO-8601 timestamp of when the install happened. */
+    installedAt: string;
+}
+/**
+ * A skill directory layout for one supported coding agent.
+ *
+ * `global` and `project` are path segments relative to the home directory and
+ * the project root respectively.
+ */
+export interface ClientDefinition {
+    /** Stable identifier shown to the user, e.g. `opencode`. */
+    id: string;
+    /** Path segments for the global skills directory. */
+    global: string[];
+    /** Path segments for the project skills directory. */
+    project: string[];
+}
+/**
+ * Supported clients and the directories in which each looks for skills.
+ */
+export declare const CLIENTS: ClientDefinition[];
+/**
+ * A detected client with both of its skill directories resolved to absolute
+ * paths.
+ */
+export interface DetectedClient {
+    /** The client identifier. */
+    id: string;
+    /** Absolute global skills directory. */
+    globalDir: string;
+    /** Absolute project skills directory. */
+    projectDir: string;
+}
+/**
+ * Inputs for installing the skill into one skills directory.
+ */
+export interface InstallOptions {
+    /** Directory holding the skill tree to copy or link. */
+    sourceDir: string;
+    /** Skills directory to install into. */
+    targetDir: string;
+    /** Package version recorded in the marker. */
+    version: string;
+    /** Create a symlink instead of copying. */
+    link?: boolean;
+    /** Report the action without writing anything. */
+    dryRun?: boolean;
+}
+/**
+ * The outcome of one install attempt.
+ */
+export interface InstallResult {
+    /** The skills directory that was targeted. */
+    targetDir: string;
+    /** The resolved destination path, `<targetDir>/fluentui-design`. */
+    dest: string;
+    /** True when the skill was copied. */
+    installed?: boolean;
+    /** True when the skill was symlinked. */
+    linked?: boolean;
+    /** True when the call ran in dry-run mode and wrote nothing. */
+    dryRun?: boolean;
+}
+/**
+ * The outcome of one uninstall attempt.
+ */
+export interface UninstallResult {
+    /** The skills directory that was targeted. */
+    targetDir: string;
+    /** The resolved destination path, `<targetDir>/fluentui-design`. */
+    dest: string;
+    /** True when the destination existed and was removed. */
+    removed: boolean;
+    /** True when the call ran in dry-run mode and wrote nothing. */
+    dryRun: boolean;
+}
+/**
+ * Options parsed from the command line.
+ */
+export interface InstallerOptions {
+    /** Explicit `--target` directories. */
+    targets: string[];
+    /** Use project-level skill directories. */
+    project: boolean;
+    /** Create a symlink instead of copying. */
+    link: boolean;
+    /** Report only; write nothing. */
+    dryRun: boolean;
+    /** Install into every detected client. */
+    all: boolean;
+}
+/**
+ * The installer sub-commands.
+ */
+export type InstallerCommand = "install" | "status" | "uninstall" | "help";
+/**
+ * The result of parsing an installer command line.
+ */
+export interface ParsedArgs {
+    /** The chosen sub-command, or `help`. */
+    command: InstallerCommand;
+    /** Parsed options. */
+    options: InstallerOptions;
+    /** A parse error message, when the input was invalid. */
+    error?: string;
+}
+/**
+ * Environment values the CLI depends on, injected so tests can run without
+ * touching the real machine.
+ */
+export interface InstallerIo {
+    /** Home directory used for global client detection. */
+    home?: string;
+    /** Project root used for project client detection. */
+    cwd?: string;
+    /** Whether interactive prompting is allowed. */
+    isTTY?: boolean;
+    /** Package version recorded in the marker; read from `package.json` when omitted. */
+    version?: string;
+    /** Override the packaged skill source directory. */
+    sourceDir?: string;
+}
+/**
+ * Resolves the packaged skill directory.
+ *
+ * Works in both layouts: shipped (`<package>/dist/skill` ->
+ * `<package>/skills`) and repository (`<repo>/src/skill` ->
+ * `<repo>/.agents/skills`). The packaged copy is preferred when both exist.
+ *
+ * @param moduleUrl - `import.meta.url` of this module.
+ * @param override - Optional explicit source directory.
+ * @returns Absolute path to the skill directory.
+ */
+export declare function resolveSourceDir(moduleUrl: string, override?: string): string;
+/**
+ * Detects which clients are present on the machine.
+ *
+ * A client is present when its global directory, the global directory's
+ * parent, or its project directory exists.
+ *
+ * @param options - Detection inputs.
+ * @param options.home - Home directory.
+ * @param options.cwd - Project root.
+ * @param options.exists - Existence predicate (injectable for tests).
+ * @returns Detected clients with resolved global and project directories.
+ */
+export declare function detectClients(options: {
+    home: string;
+    cwd: string;
+    exists: (target: string) => boolean;
+}): DetectedClient[];
+/**
+ * Resolves the skills directories to operate on.
+ *
+ * Explicit `--target` directories win, then `--project`, otherwise every
+ * detected client's global directory is used.
+ *
+ * @param options - Selection options.
+ * @param options.targets - Explicit target directories.
+ * @param options.project - Use project directories instead of global ones.
+ * @param detected - Detected clients.
+ * @returns Absolute target skills directories.
+ */
+export declare function resolveTargets(options: InstallerOptions, detected: DetectedClient[]): string[];
+/**
+ * Reads the installed marker, if present and parseable.
+ *
+ * @param targetDir - Installed skill directory.
+ * @returns The parsed marker, or undefined.
+ */
+export declare function readMarker(targetDir: string): SkillMarker | undefined;
+/**
+ * Removes control and display-formatting characters from a value before
+ * printing it.
+ *
+ * The installed version is read back from disk, so it is untrusted input; the
+ * raw value could otherwise carry terminal escape sequences or bidirectional
+ * override characters into the output.
+ *
+ * @param value - Text to sanitize.
+ * @returns The text without control or display-formatting characters.
+ */
+export declare function sanitizeForDisplay(value: string): string;
+/**
+ * Installs the skill into one skills directory by atomically replacing
+ * `fluentui-design/`.
+ *
+ * The tree is first copied into a temp sibling, then renamed over the
+ * destination. An existing destination is moved aside as a backup and restored
+ * if the rename fails, so a failed install never leaves a partial skill.
+ *
+ * @param options - Install inputs.
+ * @returns A summary of the action.
+ * @throws When the source is not a skill or the destination is unrelated.
+ */
+export declare function installSkill(options: InstallOptions): InstallResult;
+/**
+ * Removes the installed skill from one skills directory.
+ *
+ * Only the `fluentui-design/` directory is removed; any sibling skill is
+ * untouched.
+ *
+ * @param options - Uninstall inputs.
+ * @param options.targetDir - Skills directory.
+ * @param options.dryRun - Report only, write nothing.
+ * @returns A summary of the action.
+ */
+export declare function uninstallSkill(options: {
+    targetDir: string;
+    dryRun?: boolean;
+}): UninstallResult;
+/**
+ * Parses argv into a sub-command and options.
+ *
+ * @param argv - Arguments after `skill` (or the full argument list).
+ * @returns The parsed command and options, plus an error for invalid input.
+ */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/**
+ * Runs the installer CLI.
+ *
+ * @param argv - Arguments after `skill`.
+ * @param io - Injectable environment values.
+ * @returns Process exit code.
+ */
+export declare function main(argv: string[], io?: InstallerIo): Promise<number>;