@etus/seven-skill 0.1.0-beta.2 → 0.1.0-beta.4

package/.claude/skills/seven/scripts/load-context.mjs

@@ -1,84 +1,93 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: Apache-2.0
-// ETUS Digital — Seven Design System. Loader shape adapted from impeccable.
+// ETUS Digital — Seven consumer context adapter.
 
 import fs from 'node:fs'
 import path from 'node:path'
+import { createRequire } from 'node:module'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
-const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md']
-const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md']
-const FALLBACK_DIRS = ['.agents/context', 'docs']
+import { checkForUpdate } from './update-check.mjs'
 
-function firstExisting(dir, names) {
-  for (const name of names) {
-    const abs = path.join(dir, name)
-    if (fs.existsSync(abs)) return abs
-  }
-  return null
+export function argValue(name, argv = process.argv) {
+  const direct = argv.find((arg) => arg.startsWith(`${name}=`))
+  if (direct) return direct.slice(name.length + 1)
+  const index = argv.indexOf(name)
+  return index >= 0 ? argv[index + 1] : null
 }
 
-function safeRead(filePath) {
+export function findRoot(start) {
+  let current = path.resolve(start)
   try {
-    return fs.readFileSync(filePath, 'utf8')
-  } catch {
-    return null
+    if (fs.statSync(current).isFile()) current = path.dirname(current)
+  } catch {}
+  const fallbackRoot = current
+  while (true) {
+    if (fs.existsSync(path.join(current, '.seven', 'project.yml'))) return current
+    if (fs.existsSync(path.join(current, 'seven.json'))) return current
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
   }
+  return fallbackRoot
 }
 
-function resolveMaybeRelative(cwd, value) {
-  const trimmed = value.trim()
-  return path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed)
+export async function loadFromInstalledRuntime(root, target) {
+  try {
+    const require = createRequire(path.join(root, 'package.json'))
+    const manifest = require.resolve('@etus/seven/package.json')
+    const moduleUrl = pathToFileURL(path.join(path.dirname(manifest), 'lib', 'context.mjs')).href
+    const runtime = await import(moduleUrl)
+    return runtime.loadConsumerContext(root, { target })
+  } catch (error) {
+    return { runtimeError: error instanceof Error ? error.message : String(error) }
+  }
 }
 
-export function resolveContextDir(cwd = process.cwd()) {
-  const envDir = process.env.SEVEN_CONTEXT_DIR
-  if (envDir?.trim()) return resolveMaybeRelative(cwd, envDir)
-
-  if (firstExisting(cwd, [...PRODUCT_NAMES, ...DESIGN_NAMES])) return cwd
-
-  for (const rel of FALLBACK_DIRS) {
-    const candidate = path.resolve(cwd, rel)
-    if (firstExisting(candidate, [...PRODUCT_NAMES, ...DESIGN_NAMES])) return candidate
+export function fallback(root, target, runtimeError) {
+  const productPath = path.join(root, 'PRODUCT.md')
+  const product = fs.existsSync(productPath) ? fs.readFileSync(productPath, 'utf8') : null
+  let release = null
+  try {
+    release = JSON.parse(fs.readFileSync(path.join(root, '.seven', 'release.lock.json'), 'utf8'))
+  } catch {}
+  return {
+    schemaVersion: 1,
+    projectRoot: root,
+    target: path.resolve(target),
+    hasProduct: Boolean(product),
+    product,
+    productPath: product ? 'PRODUCT.md' : null,
+    productPlaceholder: !product || product.trim().length < 200 || /\b(?:TODO|TBD|placeholder)\b/i.test(product),
+    register: null,
+    project: null,
+    release,
+    surface: null,
+    runtimeAvailable: false,
+    runtimeError,
   }
-
-  return cwd
 }
 
-function extractRegister(product) {
-  if (!product) return null
-  const heading = product.match(/^##\s+Register\s*\n+([\s\S]*?)(?=\n##\s+|\s*$)/im)
-  const value = heading?.[1]?.split('\n').map((line) => line.trim()).find(Boolean)
-  if (!value) return null
-  return value.replace(/^[-*]\s*/, '').toLowerCase()
+export async function loadContext(start = process.cwd(), { target = start } = {}) {
+  const root = findRoot(start)
+  const loaded = await loadFromInstalledRuntime(root, target)
+  return loaded.runtimeError ? fallback(root, target, loaded.runtimeError) : loaded
 }
 
-function isPlaceholderProduct(product) {
-  if (!product) return false
-  return product.trim().length < 200 || /\b(?:todo|tbd|placeholder|\[todo\])\b/i.test(product)
+export async function main(argv = process.argv) {
+  const target = argValue('--target', argv) || process.env.SEVEN_TARGET || process.cwd()
+  const context = await loadContext(target, { target })
+  const update = await checkForUpdate(context.release?.sevenVersion || null)
+  process.stdout.write(`${JSON.stringify({ ...context, update }, null, 2)}\n`)
 }
 
-export function loadContext(cwd = process.cwd()) {
-  const contextDir = resolveContextDir(cwd)
-  const productPath = firstExisting(contextDir, PRODUCT_NAMES)
-  const designPath = firstExisting(contextDir, DESIGN_NAMES)
-  const product = productPath ? safeRead(productPath) : null
-  const design = designPath ? safeRead(designPath) : null
-
-  return {
-    hasProduct: !!product,
-    product,
-    productPath: productPath ? path.relative(cwd, productPath) : null,
-    productPlaceholder: isPlaceholderProduct(product),
-    register: extractRegister(product),
-    hasDesign: !!design,
-    design,
-    designPath: designPath ? path.relative(cwd, designPath) : null,
-    contextDir,
+function isCliEntry() {
+  if (!process.argv[1]) return false
+  try {
+    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(process.argv[1])
+  } catch {
+    return false
   }
 }
 
-function cli() {
-  process.stdout.write(`${JSON.stringify(loadContext(process.cwd()), null, 2)}\n`)
-}
-
-if (process.argv[1]?.endsWith('load-context.mjs')) cli()
+if (isCliEntry()) await main()

package/.claude/skills/seven/scripts/update-check.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const WEEK_MS = 7 * DAY_MS
+
+function cachePath(env = process.env) {
+  return env.SEVEN_UPDATE_CACHE || path.join(os.homedir(), '.seven', 'update-check.json')
+}
+
+function readCache(env) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cachePath(env), 'utf8'))
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+function writeCache(cache, env) {
+  try {
+    const destination = cachePath(env)
+    fs.mkdirSync(path.dirname(destination), { recursive: true })
+    fs.writeFileSync(destination, `${JSON.stringify(cache, null, 2)}\n`)
+  } catch {
+    // Update discovery is best-effort and must never block the UI workflow.
+  }
+}
+
+function semverParts(value) {
+  const match = String(value || '').trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/)
+  if (!match) return null
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ? match[4].split('.') : [],
+  }
+}
+
+function compareIdentifier(left, right) {
+  const leftNumber = /^\d+$/.test(left) ? Number(left) : null
+  const rightNumber = /^\d+$/.test(right) ? Number(right) : null
+  if (leftNumber != null && rightNumber != null) return Math.sign(leftNumber - rightNumber)
+  if (leftNumber != null) return -1
+  if (rightNumber != null) return 1
+  return left.localeCompare(right)
+}
+
+export function compareSemver(left, right) {
+  const a = semverParts(left)
+  const b = semverParts(right)
+  if (!a || !b) return 0
+  for (let index = 0; index < 3; index++) {
+    if (a.core[index] !== b.core[index]) return Math.sign(a.core[index] - b.core[index])
+  }
+  if (a.prerelease.length === 0 && b.prerelease.length > 0) return 1
+  if (b.prerelease.length === 0 && a.prerelease.length > 0) return -1
+  for (let index = 0; index < Math.max(a.prerelease.length, b.prerelease.length); index++) {
+    if (a.prerelease[index] == null) return -1
+    if (b.prerelease[index] == null) return 1
+    const compared = compareIdentifier(a.prerelease[index], b.prerelease[index])
+    if (compared !== 0) return compared
+  }
+  return 0
+}
+
+async function fetchLatest(env) {
+  const registry = (env.SEVEN_UPDATE_REGISTRY || 'https://registry.npmjs.org').replace(/\/$/, '')
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 1500)
+  try {
+    const response = await fetch(`${registry}/%40etus%2Fseven/latest`, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal,
+    })
+    if (!response.ok) return null
+    const payload = await response.json()
+    return typeof payload?.version === 'string' ? payload.version : null
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export async function checkForUpdate(currentVersion, { env = process.env, now = Date.now() } = {}) {
+  if (!currentVersion || env.SEVEN_NO_UPDATE_CHECK) return null
+  const cache = readCache(env)
+  const fresh = typeof cache.checkedAt === 'number' && now - cache.checkedAt < DAY_MS
+  let latestVersion = fresh ? cache.latestVersion : await fetchLatest(env)
+  if (!latestVersion) latestVersion = cache.latestVersion || null
+  if (!fresh && latestVersion) {
+    cache.checkedAt = now
+    cache.latestVersion = latestVersion
+  }
+  if (!latestVersion) return null
+
+  const available = compareSemver(latestVersion, currentVersion) > 0
+  const notify = available && (
+    cache.notifiedVersion !== latestVersion ||
+    typeof cache.notifiedAt !== 'number' ||
+    now - cache.notifiedAt >= WEEK_MS
+  )
+  if (notify) {
+    cache.notifiedVersion = latestVersion
+    cache.notifiedAt = now
+  }
+  writeCache(cache, env)
+  return {
+    package: '@etus/seven',
+    currentVersion,
+    latestVersion,
+    available,
+    notify,
+    command: `pnpm add -D @etus/seven@${latestVersion} && pnpm exec seven update`,
+  }
+}

package/.claude-plugin/marketplace.json

@@ -11,8 +11,8 @@
   "plugins": [
     {
       "name": "seven",
-      "description": "Seven Design System skill, plugin, and CLI detector for AI coding agents — ETUS Digital",
-      "version": "0.1.0-beta.2",
+      "description": "Provider-native Seven Design System skills and deterministic UI detector runtime for @etus/seven consumers — ETUS Digital",
+      "version": "0.1.0-beta.4",
       "author": {
         "name": "ETUS Digital",
         "url": "https://github.com/etusdigital"

package/.claude-plugin/plugin.json

@@ -1,12 +1,17 @@
 {
   "name": "seven",
-  "description": "Seven Design System skill, plugin, and CLI detector for AI coding agents — ETUS Digital",
-  "version": "0.1.0-beta.2",
+  "description": "Provider-native Seven Design System skills and deterministic UI detector runtime for @etus/seven consumers — ETUS Digital",
+  "version": "0.1.0-beta.4",
   "author": {
     "name": "ETUS Digital",
     "url": "https://github.com/etusdigital"
   },
   "homepage": "https://github.com/etusdigital/seven#readme",
   "repository": "https://github.com/etusdigital/seven.git",
-  "skills": "./.claude/skills/"
+  "skills": "./.claude/skills/",
+  "agents": [
+    "./.claude/agents/seven-asset-producer.md",
+    "./.claude/agents/seven-finish-reviewer.md",
+    "./.claude/agents/seven-manual-edit-applier.md"
+  ]
 }

package/.cursor/skills/seven/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: seven
+description: "Use for every UI task in a project governed by the Seven Design System: creating or editing React 19 components, pages, flows, layouts, styles, UX copy, responsive behavior, accessibility, visual critique, performance, hardening, documentation, reusable compositions, browser iteration, or final polish. Requires Seven context before edits, reuse of installed Seven components and declared variants, @etus/tokens-only visual values, pt-BR product voice, and deterministic Seven validation. Routes the complete Seven workflow catalog plus doctor, hooks, pins, and exceptions. Do not trigger for backend-only or infrastructure-only work."
+version: 0.1.0-beta.4
+license: Apache-2.0
+---
+
+# Seven UI governance
+
+Builds production interfaces that stay inside the installed Seven release. This is not a visual inspiration prompt: Seven components, variants, tokens, interaction behavior, accessibility rules, and pt-BR voice are hard product constraints.
+
+## Mandatory loop for every UI task
+
+Before reading broadly or editing any UI file:
+
+1. Identify the exact target file, application, and surface.
+2. Load the consumer context once, in full:
+
+   ```bash
+   node .cursor/skills/seven/scripts/load-context.mjs --target path/to/target
+   ```
+
+3. Read the returned `PRODUCT.md`, matched `.seven/project.yml` integration, release lock, and surface brief. If product context is missing or placeholder, ask the user directly for the missing product decision before editing UI. Do not invent users, workflow, tone, or product priorities.
+   If the result contains `update.notify: true`, finish the requested work first and then mention the exact update command once. Never update the pinned Seven release implicitly.
+4. Run `seven doctor --quick --target path/to/target`. If the Seven release, provider artifacts, or policy is inconsistent, surface that drift before producing UI.
+5. Search the installed Seven registry before creating a primitive: `seven list <need>` and `seven info <component>`. Import or install the existing component. Do not rebuild it with raw HTML.
+6. Inspect the selected component's public props and variants. If a required variant is absent, stop and surface a design-system gap. Seven allows no variants in code that do not exist in the shipped component contract.
+7. Make the smallest scoped change that satisfies the product job and all Seven rules.
+8. Run `seven check --file path/to/changed-file` for each UI file changed. Resolve errors and warnings. Advisory findings are design review input, not permission to silently redesign adjacent surfaces.
+
+Never create or edit `.github/**` as part of this workflow. Seven governance is local to the consumer project; GitHub CI is outside this skill's scope.
+
+## Context model
+
+- `PRODUCT.md` owns product facts: users, jobs, voice, accessibility needs, constraints, and non-goals.
+- `.seven/project.yml` owns integration facts: project/app roots, source roots, surface mapping, and policy profile.
+- `.seven/surfaces/*.md` owns a surface-specific brief and known states.
+- `.seven/release.lock.json` and `.seven/policy.json` identify the exact Seven release and deterministic policy installed in this project.
+- Consumer context cannot override Seven visual values. Do not create or consult a project `DESIGN.md` as a visual override.
+
+If context conflicts, surface the conflict. Product facts may specialize the workflow and copy, but they cannot invent colors, typefaces, radii, shadows, variants, or component APIs.
+
+## Source-of-truth ladder
+
+For a consumer project, use this order:
+
+```text
+installed Seven component API + installed Seven CSS/token artifacts
+  > exact release policy and registry metadata
+  > Seven reference material in this skill
+  > surface brief
+  > PRODUCT.md
+  > task prose and other project docs
+```
+
+The canonical Seven release is derived from the Seven Figma source of truth. Do not reach past the installed, locked release to copy a newer Figma value into one consumer project.
+
+## Seven design laws
+
+### Components and composition
+
+- Prefer an installed `@etus/ui` or Seven registry component over raw interactive HTML and local reimplementation.
+- Raw `<button>`, `<input>`, `<select>`, `<textarea>`, and `<dialog>` belong only inside the configured Seven component directory.
+- Keep page components as composition. Do not fork a primitive to achieve one screen-specific appearance.
+- Never invent a prop or variant. If Seven lacks one, report the gap with the component, desired behavior, and affected surface.
+
+### Color and tokens
+
+- Use declared Seven CSS variables only. Never invent a `var(--token)` name or define a consumer visual token that shadows Seven.
+- OKLCH is the token source format; runtime UI consumes `var(--token)`.
+- Mint and lime are the brand colors. Fuchsia is chart-only, never UI chrome.
+- Pure `#000` and `#fff` are banned. Use Seven's true grey neutral and semantic status ramps.
+- Tailwind v4 arbitrary color values require `color:`: `bg-[color:var(--primary)]`.
+- Tailwind v4 font-size and other ambiguous lengths require `length:`: `text-[length:var(--text-sm)]`.
+- Do not use raw Tailwind palette colors such as `bg-green-500`.
+
+See [reference/color-and-contrast.md](reference/color-and-contrast.md).
+
+### Typography and copy
+
+- Inter is the only sans face. JetBrains Mono is the only mono face.
+- Space Grotesk and Geist are legacy exploration and must not ship.
+- Product chrome is Brazilian Portuguese, sentence case, with imperative action labels and no trailing periods.
+- Never introduce European Portuguese vocabulary in pt-BR surfaces.
+- Use clear heading hierarchy and readable line length/leading.
+
+See [reference/typography.md](reference/typography.md) and [reference/ux-writing.md](reference/ux-writing.md).
+
+### Shape, elevation, and shell
+
+- Use the component radius scale (4/8/12) for controls and the surface scale (16/20/24/32) for containers. Never mix the two radius stacks.
+- Pill radius is for badges, tags, avatar triggers, and status indicators — never on buttons.
+- Borders carry hierarchy; shadows are reserved for overlays.
+- Sidebar and topbar use `var(--surface)` with no border and no shadow. The secondary panel owns the only shell divider.
+- The app shell is L-shaped: `Sidebar` and `SidebarInset` are siblings under one `SidebarProvider`; `Topbar` is inside `SidebarInset`, and every collapsible mobile shell exposes `SidebarTrigger` in `TopbarLeading`. Below `md`, collapse long breadcrumbs/actions so `TopbarLeading` cannot overflow under the trailing chrome. Never build a full-width T-shaped header or offset content manually.
+- Sidebar has exactly three state owners: `open` for the desktop panel, `openMobile` for the Sheet, and transient `railExpanded` for the dual Rail overlay. Default to `mode="single"` + icon collapse. In dual mode, every `SidebarRailButton` has `label`, links use `asChild`, hover OR focus keeps the 64→200px overlay open, and the mobile panel remains full-width regardless of desktop collapse.
+
+See [reference/spatial-design.md](reference/spatial-design.md) and [reference/app-shell.md](reference/app-shell.md).
+
+### Motion and accessibility
+
+- Default motion is 200 ms with `var(--ease-default)`. No bounce or spring in chrome.
+- Every clickable affordance uses the system-wide tactile micro-press and visible focus treatment.
+- Preserve semantic elements, accessible names, keyboard operation, logical focus, reduced motion, and WCAG AA contrast.
+- Images need real sources, dimensions, useful alternative text, and a non-broken fallback.
+
+See [reference/motion-design.md](reference/motion-design.md).
+
+## Exceptions and baselines
+
+Do not add, broaden, renew, or suppress an exception on your own. Explain the exact rule, file/value, tradeoff, owner, issue, and expiry; then obtain explicit user authorization before running `seven exceptions add` or replacing a baseline.
+
+Local hook ignores only reduce machine-local agent noise. They do not change the shared `seven check` result. A migration baseline can shrink but must never grow implicitly.
+
+## Intent routing
+
+When invoked without an intent, read [reference/routing.md](reference/routing.md) and recommend rather than auto-running a workflow.
+
+| Intent                               | Required reference                                 | Outcome                                                                                                       |
+| ------------------------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `/seven init`       | [reference/init.md](reference/init.md)             | Capture product/app/surface context required by every later workflow                                          |
+| `/seven shape`      | [reference/shape.md](reference/shape.md)           | Resolve product job, information architecture, component choices, states, and responsive behavior before code |
+| `/seven document`   | [reference/document.md](reference/document.md)     | Document how the project uses its exact Seven release without creating a competing visual authority           |
+| `/seven extract`    | [reference/extract.md](reference/extract.md)       | Extract repeated compositions while preserving Seven primitives, tokens, and public contracts                 |
+| `/seven critique`   | [reference/critique.md](reference/critique.md)     | Produce and persist a prioritized visual/product critique; do not edit by default                             |
+| `/seven audit`      | [reference/audit.md](reference/audit.md)           | Evidence-only technical audit across accessibility, performance, theming, responsiveness, and Seven drift     |
+| `/seven polish`     | [reference/polish.md](reference/polish.md)         | Scoped final pass that fixes root-cause drift and reruns checks                                               |
+| `/seven bolder`     | [reference/bolder.md](reference/bolder.md)         | Increase one target's hierarchy using only existing Seven roles and variants                                  |
+| `/seven quieter`    | [reference/quieter.md](reference/quieter.md)       | Reduce visual noise without erasing hierarchy or Seven identity                                               |
+| `/seven distill`    | [reference/distill.md](reference/distill.md)       | Remove unnecessary UI, states, and decisions while preserving the core job                                    |
+| `/seven harden`     | [reference/harden.md](reference/harden.md)         | Complete accessibility, error, loading, empty, content-stress, and recovery behavior                          |
+| `/seven onboard`    | [reference/onboard.md](reference/onboard.md)       | Design first-run, setup, empty, and activation experiences; context capture belongs to `init`                 |
+| `/seven animate`    | [reference/animate.md](reference/animate.md)       | Add only motion that explains feedback, state, or spatial continuity using Seven motion tokens                |
+| `/seven colorize`   | [reference/colorize.md](reference/colorize.md)     | Improve semantic color hierarchy using the installed Seven token roles only                                   |
+| `/seven typeset`    | [reference/typeset.md](reference/typeset.md)       | Refine typography with Seven Text roles, Inter, JetBrains Mono, measure, and content stress                   |
+| `/seven layout`     | [reference/layout.md](reference/layout.md)         | Improve composition, density, alignment, responsive reflow, and reading order                                 |
+| `/seven delight`    | [reference/delight.md](reference/delight.md)       | Add restrained, product-specific moments that improve confidence or comprehension                             |
+| `/seven clarify`    | [reference/clarify.md](reference/clarify.md)       | Rewrite UX copy in Brazilian Portuguese without changing product meaning                                      |
+| `/seven adapt`      | [reference/adapt.md](reference/adapt.md)           | Rethink an existing React web surface for another viewport, input mode, or usage context                      |
+| `/seven optimize`   | [reference/optimize.md](reference/optimize.md)     | Measure and improve loading, rendering, assets, responsiveness, and perceived performance                     |
+| `/seven overdrive`  | [reference/overdrive.md](reference/overdrive.md)   | Apply one justified high-ambition enhancement with fallbacks and a measured budget                            |
+| `/seven live`       | [reference/live.md](reference/live.md)             | Run a local browser-edit session whose accepted changes become validated source edits                         |
+| `/seven doctor`     | [reference/doctor.md](reference/doctor.md)         | Diagnose release, provider, hook, context, exception, dependency, pin, and local pre-commit health            |
+| `/seven hooks`      | [reference/hooks.md](reference/hooks.md)           | Inspect or manage local consumer agent hooks and machine-local noise controls                                 |
+| `/seven exceptions` | [reference/exceptions.md](reference/exceptions.md) | Manage explicit, owned, expiring shared waivers                                                               |
+
+When an intent is invoked, read its reference completely before acting. `audit` reports; it does not silently fix. `polish` may edit only the agreed target.
+
+Use `seven pin <workflow>` to install a provider-native standalone shortcut and `seven unpin <workflow>` to remove only Seven-owned shortcuts. Pins never change policy and never create `.github/**`.
+
+## Completion evidence
+
+A UI task is complete only when the response names:
+
+- the product/surface context used;
+- the existing Seven components and declared variants chosen;
+- the changed UI files;
+- the exact `seven check` scope and result;
+- any unresolved warning, advisory, missing contract, or user-authorized exception.
+
+Do not claim strict Seven compliance from visual resemblance, compilation alone, or a downloaded skill alone.

package/.cursor/skills/seven/reference/adapt.md

@@ -0,0 +1,34 @@
+# Adapt — rethink for another web context
+
+Adapt an existing React 19 interface to another viewport, input mode, orientation, density, connection, or usage context. This workflow is web-only; native iOS, Android, Svelte, and other framework adapters are intentionally outside Seven's contract.
+
+## Compare contexts
+
+Document the source and target for:
+
+- user job and urgency;
+- available width/height and orientation;
+- pointer, touch, keyboard, and hover capabilities;
+- information density and content extremes;
+- connectivity and device performance;
+- which behaviors must remain identical.
+
+Adaptation is not proportional scaling. Preserve information architecture unless product evidence requires a change, but recompose how it is exposed.
+
+## Apply with Seven
+
+- Start from narrow, content-driven layout rules and add complexity with container or `min-width` queries.
+- Use existing responsive behavior and props on Seven components before custom CSS.
+- Reflow side-by-side regions, keep reading and DOM order logical, and prevent horizontal page scroll.
+- Keep primary functionality available on every supported width; use disclosure, not deletion.
+- Provide at least 44×44 CSS px touch targets for coarse pointers without forcing all desktop density to match.
+- Never rely on hover for meaning or access. Use `(hover: hover)` only for enhancements.
+- Bound wide desktop content; do not stretch forms or prose across a 4K canvas.
+- Handle safe areas and the on-screen keyboard when the target includes mobile web.
+- Use responsive images with correct dimensions, `srcset`/`sizes`, and art direction only when crops genuinely differ.
+
+Do not hardcode device names or fork separate mobile/desktop component trees without a demonstrated semantic need.
+
+## Verify
+
+Test the actual supported breakpoint boundaries, 320 px, zoomed desktop, portrait/landscape, keyboard-only, coarse/fine pointer, long pt-BR strings, reduced motion, and at least one real lower-performance device when risk warrants it. Run Seven checks on all changed files and browser checks against the rendered target.

package/.cursor/skills/seven/reference/animate.md

@@ -0,0 +1,31 @@
+# Animate — motion with a job
+
+Add motion only when it explains feedback, state, hierarchy, or spatial continuity. Read [motion-design.md](motion-design.md) completely before editing.
+
+## Motion thesis
+
+Before implementation, identify:
+
+- the state or relationship that is currently hard to understand;
+- the smallest motion that would clarify it;
+- frequency, interruption behavior, and performance budget;
+- reduced-motion equivalent;
+- the existing Seven component or motion token that owns the behavior.
+
+If removing the animation would lose no meaning or confidence, do not add it.
+
+## Seven constraints
+
+- Routine feedback uses `var(--duration-fast)`; normal transitions use `var(--duration-normal)`; bounded surface entries may use `var(--duration-slow)`.
+- Use `var(--ease-default)` or the documented Seven exit/entry easing. No bounce, spring, elastic, wiggle, marquee, pulsing chrome, or decorative looping.
+- Animate transform and opacity by default. Do not animate width, height, top, left, margin, or other layout-driving properties.
+- Preserve content visibility in the non-enhanced state.
+- Use the existing tactile micro-press. Do not layer a second hover-lift language over it.
+- Loading is a Seven Skeleton or Spinner appropriate to the region, not a bespoke animation.
+- Reduced motion must keep state changes perceivable with near-instant transitions.
+
+Do not add a motion dependency for behavior the current stack or Seven component already provides. Any new dependency or browser API with partial support requires explicit user approval and a functional fallback.
+
+## Verify
+
+Exercise repeated triggers, interruption, rapid reversal, keyboard activation, reduced motion, background-tab behavior, and a representative mid-range device. Confirm no layout shift, hidden-at-rest content, or long-task illusion. Run Seven checks and relevant interaction tests.