M3Surface as new basic primitive for panels, dialogs, side sheets, etc + Storybook improvements

.gitignore

@@ -19,3 +19,5 @@ node_modules/
 .pnp.loader.mjs
 .yarnrc.yml
 *storybook.log
+.env
+drafts/

AGENTS.md

@@ -11,12 +11,6 @@
   respond in that language.
 - If a message is mixed-language, reply in the dominant language unless the
   user specifies otherwise.
-- Run `make eslint` before handoff or commit preparation only when changed
-  files include code covered by eslint rules (for example `*.js`, `*.ts`,
-  and similar source files). Do not run `make eslint` for markdown-only
-  changes (for example `*.md`).
-- Getter/helper functions must be side-effect free. Side effects are allowed
-  only by prior agreement and only when there are strong, explicit reasons.
 
 ## Reporting
 - Keep handoff reports natural and outcome-focused: describe what was done.
@@ -26,9 +20,9 @@
   affect correctness, safety, or reproducibility.
 
 ## Purpose
-This file defines practical instructions for working in the
-`modulify/m3-web` repository, with a focus on test execution and commit
-workflow.
+This file defines practical instructions for day-to-day work in the
+`modulify/m3-web` repository, with a focus on repository conventions,
+test execution, and standard local commands.
 
 ## Repository Structure
 - This project is a Yarn Workspaces monorepo.
@@ -38,13 +32,27 @@ workflow.
 - Vitest workspace targets are declared in `vitest.workspace.ts`:
   `m3-react`, `m3-vue`.
 
-## Local Environment Prerequisites
+## Architecture Rules
+- Getter/helper functions must be side-effect free. Side effects are allowed
+  only by prior agreement and only when there are strong, explicit reasons.
+- Tests inside a workspace must cover only code owned by that workspace. In
+  `m3-foundation`, `m3-react`, `m3-vue`, and any future workspace, do not add
+  tests for implementation that belongs to another workspace.
+- Cross-workspace imports must go through the target workspace package name as
+  declared in `package.json`. Relative or absolute filesystem imports into
+  another workspace are forbidden. For example,
+  `import type { Appearance } from '@modulify/m3-foundation/types/components/button'`
+  is allowed, but
+  `import type { Appearance } from '../../../m3-foundation/types/components/button'`
+  is not.
+
+## Local setup
 - Yarn version is `4.6.0` (see `packageManager` in `package.json`).
-- Local `.yarnrc.yml` is generated from `.yarnrc.yml.dist` using:
+- Generate local `.yarnrc.yml` from `.yarnrc.yml.dist`:
 ```bash
 make .yarnrc.yml
 ```
-- Install dependencies with:
+- Install dependencies:
 ```bash
 make node_modules
 # or
@@ -54,16 +62,6 @@ yarn install
 ## Running Tests
 
 ### Local Path
-- Generate local Yarn config:
-```bash
-make .yarnrc.yml
-```
-- Install dependencies:
-```bash
-make node_modules
-# or
-yarn install
-```
 - Run all tests:
 ```bash
 make test
@@ -104,44 +102,47 @@ make help
 ```
 
 ## Important Project Rules
-- Commit messages follow Conventional Commits.
-- Commitlint configuration is in `.commitlintrc.json` with:
-  `header-max-length=200`, `body-max-line-length=200`,
-  `footer-max-line-length=200`, `subject-case=never`.
-- Getter/helper functions must be side-effect free. Side effects are allowed
-  only by prior agreement and only when there are strong, explicit reasons.
+- Before performing actions, analyze whether there is a suitable local skill
+  for the task and consult it for detailed instructions.
+- Before performing repeated or operational actions, inspect `make help` and
+  its output to see whether an existing recipe already covers the task.
+- If a suitable recipe exists, prefer it over ad hoc commands to reduce extra
+  work, keep workflows standardized, and avoid unnecessary escalations.
+- The project includes a Playwright container and make recipes for screenshot
+  capture; use them when visual analysis of Storybook pages, component states,
+  or other UI behavior is helpful.
+- The project also includes runtime-analysis research recipes for DOM, styles,
+  layout metrics, a11y snapshots, traces, network/performance logs, token
+  diffs, and screenshot matrices; use them to reduce uncertainty and to
+  understand what is going wrong before guessing at visual or runtime issues.
+  Read `docs/en/runtime-analysis-recipes.md` first when the task involves
+  visual regressions, layout ambiguity, token/theme uncertainty, unclear
+  animation behavior, or other runtime issues where these recipes may help.
+- Run eslint before handoff or commit preparation only when changed files
+  include code covered by eslint rules (for example `*.js`, `*.ts`, and
+  similar source files). Do not run eslint for markdown-only changes.
+- Prefer running eslint with `--fix` when available so autofixable issues are
+  resolved automatically before manual follow-up.
+
+## Skills
+The skills listed below are stored locally in this repository under `skills/`.
+
+If the context was compacted and you see `Context compacted`, reread any skill
+whose description below starts with `[reread]` after the colon before
+continuing.
 
-## Commit Workflow
-- Default commit message language is English (unless explicitly requested
-  otherwise).
-- Commit style is Conventional Commits.
-- Write commit subjects as historical facts (not intentions).
-- Start commit subject description with an uppercase letter.
-- Keep commit subject description concise.
-- Move long details to commit body; lists in body are allowed for enumerations.
-- Use past/perfective wording; prefer passive voice for changelog-friendly phrasing.
-Examples: `Added ...`, `Removed ...`, `Refactored ...`, `Fixed ...`.
-- Respect commitlint limits from `.commitlintrc.json`:
-  `header-max-length=200`, `body-max-line-length=200`,
-  `footer-max-line-length=200`.
-- For workspace commits, use scope equal to the workspace directory name:
-  `m3-foundation`, `m3-react`, `m3-vue`.
-- Split commits by logical change. Workspace-local changes should stay in
-  their workspace scope.
-- Changes in `yarn.lock` must always be committed separately from all other files.
-- Commit message for `yarn.lock`-only commit must be exactly:
-`chore: Updated yarn.lock`.
-- Exception for intentional dependency updates:
-if commit purpose is dependency update (`yarn up`, `yarn add`, `yarn remove`, etc.),
-after rebase conflict resolution rerun the original dependency command and recreate separate
-`chore: Updated yarn.lock` commit.
-- Exception: global workspace-level changes can be combined in one commit.
-Global examples: eslint rule updates, shared dependency updates, repository-level infra/config changes.
-- For commit tasks, use the local skill:
-`skills/commit-workflow/SKILL.md`.
-- For `yarn.lock` merge/rebase conflict resolution, use the local skill:
-`skills/yarn-lock-conflict-resolution/SKILL.md`.
-- For coverage deficit analysis and recovery strategy, use the local skill:
-`skills/coverage-recovery/SKILL.md`.
-- For documentation creation or edits under `docs/` with locale parity, use the local skill:
-`skills/docs-parity/SKILL.md`.
+- `commit-workflow`: [reread] Use when creating or splitting git commits in
+  this repository. Reread it before every commit creation; it standardizes
+  commit grouping, Conventional Commits, workspace scopes, and commitlint
+  limits.
+- `coverage-recovery`: Use when coverage is below target or uncovered code must
+  be analyzed and closed without adding artificial tests.
+- `docs-parity`: Use when creating or editing files under `docs/`. Keeps
+  English-first edits, locale parity, and locale index updates aligned.
+- `exploration-workflow`: [reread] Use only when the user explicitly switches
+  the task into exploration mode: autonomous hypothesis-driven work on
+  uncertain functionality, with timeboxing, milestone logging, and tightly
+  controlled pre-agreed escalation windows, plus `drafts/current.yml` and a
+  dedicated `drafts/` activity directory for logs, facts, and artifact links.
+- `yarn-lock-conflict-resolution`: Use when resolving merge or rebase conflicts
+  in `yarn.lock` according to repository policy.