diff --git a/AGENTS.md b/AGENTS.md index 0b5dc97..212bc33 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,68 +1,54 @@ # InKCre UI -This repository owns the InKCre design system and UI libraries. +The InKCre design system and UI libraries. Ships `@inkcre/ui-web`, the design-token source, and the generated consumer Agent skill consumed by InKCre peers. -Reason in English. Communicate with humans in Chinese. +## Mental Model -## Repository Map - -- `packages/web/`: `@inkcre/ui-web`, its public components, styles, stories, - generated consumer skill, and package-local instructions. -- `tokens/inkcre.tokens.json`: 仓库维护的设计 Token 规范源，使用 `type/value`；Figma 仅提议已有路径的值更新，格式与维护入口见 [Token 指南](tokens/tokens.md)。 -- `scripts/`: deterministic token, package-metadata, Agent Skill, contract, and - release preparation commands. -- `docs/index.md`: durable documentation navigation. -- `tasks/`: volatile task packets retained only while their parent task is active. - -## Knowledge Owners +InKCre is a system of heterogeneous peers sharing one info-base. Peers differ in runtime capability, not in authority: no fixed frontend/backend hierarchy exists. -UI 设计、组件、Token 或视觉审视工作从 [DESIGN.md](DESIGN.md) 的总纲和阅读路径进入，只读取与任务有关的设计正文。`docs/design/` 分别维护设计立场、视觉语言、页面组合与判断依据；纯构建和非 UI 工作无需加载这些正文。具体值与 API 仍由下面的源头负责。 +UI is a cross-cutting product surface, not a peer implementation. Any peer that renders to a human — web, browser extension, future native — consumes the same design system. The design system owns design relationships, visual language, and component APIs; consuming peers own business flows and layout. -- Repository and package entry points: `README.md` and `packages/web/README.md`. -- Public package API: package exports, component manifest, TypeScript source, - generated declarations, and styles. -- Component usage evidence: `packages/web/stories/`. -- UI consumer Agent guidance: `packages/web/skill.seed.json` and the generated - `packages/web/skills/ui-web/` artifact. -- Package migration contract: `packages/web/MIGRATION.md`. -- Build, release, preview, and production behavior: package scripts, repository - scripts, and `.github/workflows/`. -- Repeated subtree hazards: the nearest local `AGENTS.md`. +Design tokens are the single source for names, types, values, and references. Figma proposes value updates to existing paths; it does not author the token schema. Components and their TypeScript declarations own API facts. Stories own usage evidence. -## 设计变更的维护责任 +## Knowledge Owners -先明确变化要保持的设计关系，再确定修改位置。已有角色是否可复用，取决于共同用途与共同变化理由；新增共享能力应说明实际情境、现有缺口、默认行为、允许变化和覆盖责任。可以在变更说明中自然表达，无须另建统一模板。 +`ui` is an SVC Spoke. Shared Hub truth is mounted read-only at `docs/_shared/` (git submodule → `InKCre/docs`). -设计正文拥有已确认的选择及其理由，Token 源拥有名称、类型、值与引用，组件源码和声明拥有 API 事实。实现观察、提炼过程、待确认方案与讨论状态记录在 task packet，确认后的结论才进入正式正文。当前表现与认可要求不一致时应明确指出差异，按任务授权修复或提出规则变更，不能只为解释代码而修改要求。 +- Design stance, visual language, composition, and rationale: `DESIGN.md` and `docs/design/` +- Design-token source: `tokens/inkcre.tokens.json` (see `tokens/tokens.md` for format and maintenance) +- Public package API: `packages/web/` exports, component manifest, TypeScript sources, generated declarations, styles +- Component usage evidence: `packages/web/stories/` +- UI consumer Agent guidance: `packages/web/skill.seed.json` and the generated `packages/web/skills/ui-web/` +- Package migration contract: `packages/web/MIGRATION.md` +- Build, release, preview, and production behavior: package scripts, repository scripts, `.github/workflows/` +- Product behavior and language: `docs/_shared/10-prd/` +- Cross-unit contracts and topology: `docs/_shared/20-product-tdd/` +- Volatile task state: `tasks/` +- Subtree-specific hazards: the nearest local `AGENTS.md` -改变公开名称、用途、默认表现或交互承诺时，同步相应实现、设计正文、示例和迁移说明。静态检查确认交付事实，真实场景确认设计关系与表现；视觉验收需要说明比较依据，不能只报告 Token 合法或构建成功。 +## Repository Map -## Coding Guidelines +- `packages/web/`: `@inkcre/ui-web` package — public components, styles, stories, generated consumer skill, package-local instructions +- `tokens/inkcre.tokens.json`: design-token source using `type/value` +- `scripts/`: deterministic token, package-metadata, Agent-skill, contract, and release-preparation commands +- `docs/design/`: design stance, visual language, page composition, judgment rationale +- `docs/index.md`: durable documentation navigation +- `tasks/`: volatile task packets -- [Coding for Human](.github/instructions/coding-for-human.instructions.md) +## Development Constraints -## Development Workflow +- Runtime: Node.js 22.22.3; package manager: pnpm 11.17.0. Exact commands live in `package.json` and repository scripts. +- Generated tokens, package metadata, and `skills/ui-web` are checked-in projections. Change their source owner and run `pnpm generate`; do not edit generated output directly. +- Use `pnpm changeset` for any observable published-package change. +- Changing a public name, purpose, default behavior, or interaction promise requires synchronized updates to the implementation, design prose, examples, and migration notes. +- Visual acceptance requires naming the comparison basis; reporting only "tokens are valid" or "build succeeded" is not acceptance. -- Follow the organization-wide [Git and GitHub Governance](https://github.com/InKCre/.github/blob/main/GOVERNANCE.md) - and [contribution workflow](https://github.com/InKCre/.github/blob/main/CONTRIBUTING.md) for branches, pull requests, - release authority, and delivery boundaries; repository-local documents own exact commands. -- Never edit `docs/_shared/**` from this Spoke. Use - `.agents/skills/edit-svc-shared-docs/` to change the Hub source first and bump - the local shared reference separately. -- Runtime: Node.js 22.22.3; package manager: pnpm 11.17.0. -- Install with `pnpm install --frozen-lockfile`; run the full contract with - `pnpm check`. -- Use `pnpm changeset` for an observable published-package change. -- Generated tokens, package metadata, and `skills/ui-web` are checked-in - projections. Change their source owner and run `pnpm generate`; do not edit - generated output directly. -- Follow the organization-wide [Verification and Test Policy](https://github.com/InKCre/.github/blob/main/TESTING.md). - This repository prefers type-check, lint, generated-contract checks, story builds, and real - consuming-page review; it currently admits no automated unit/component suite. -- Require explicit Human authorization before commit, push, publication, or - external repository/settings mutation. +## Governance And Workflow -当前任务的范围、决策与验证记录保存在 [UI 基础能力工作包](tasks/ui-foundations/packet.md)。继续本任务时先读取工作包和当前组；它不替代上述长期知识入口，也不将尚未启动的组视为实现授权。 +- Git and GitHub workflow: [Git and GitHub Governance](https://github.com/InKCre/.github/blob/main/GOVERNANCE.md) and [Contributing](https://github.com/InKCre/.github/blob/main/CONTRIBUTING.md) +- Verification and test selection: [Verification and Test Policy](https://github.com/InKCre/.github/blob/main/TESTING.md) +- Coding guidelines: `.github/instructions/coding-for-human.instructions.md` +- Hub-Spoke shared-doc workflow: `.agents/skills/edit-svc-shared-docs/` ## SVC @@ -70,9 +56,6 @@ UI 设计、组件、Token 或视觉审视工作从 [DESIGN.md](DESIGN.md) 的 Use `svc --help` or `svc --help`. - `svc status`: inspect project state -- `svc lookup`: read SVC guidance -- `svc task init`: create a task packet -- `svc task grow`: inspect packet shape without changing files - `svc dev`: manage declared development targets If `AGENTS.local.md` exists, read it after this file. It is ignored local guidance; shared rules belong here. diff --git a/README.md b/README.md index b509cbe..49b7bcd 100644 --- a/README.md +++ b/README.md @@ -104,31 +104,28 @@ republishing the other. `wrangler.toml` owns the Pages project name, output directory, and compatibility date. Delivery jobs run through GitHub environments; the Cloudflare credential remains a selected organization Actions secret. -## Joint development with client-web +## Joint development with impl-ts The consuming Vite/Vitest/TypeScript pipeline owns source consumption. Keep this workspace installed and generated, then opt in from a sibling -`client-web` checkout: +`impl-ts` checkout: ```bash pnpm install --frozen-lockfile pnpm generate -pnpm --dir ../client-web dev:ui --ui-source ../ui/packages/web +pnpm --dir ../impl-ts dev:ui --ui-source ../ui/packages/web ``` -Replace `../ui` with this checkout's actual location while the local directory -is still named `design` or is stored elsewhere. - The command validates this package root and maps only its public specifiers for the current development process. It does not use `pnpm link`, persist an absolute path, or modify either manifest or lockfile. Token JSON changes still require `pnpm generate`. Run the consumer source-graph check with -`pnpm --dir ../client-web type-check:ui --ui-source ../ui/packages/web`. +`pnpm --dir ../impl-ts type-check:ui --ui-source ../ui/packages/web`. Normal client development, builds, checks, and CI remain pinned to the published registry artifact. The consumer's -[`docs/40-deployment/development-runtime.md`](https://github.com/InKCre/client-web/blob/main/docs/40-deployment/development-runtime.md#joint-development-lanes) +[`docs/40-deployment/development-runtime.md`](https://github.com/InKCre/impl-ts/blob/main/docs/40-deployment/development-runtime.md#joint-development-lanes) owns the full startup, remotes, cleanup, troubleshooting, and release-fidelity contract. diff --git a/docs/index.md b/docs/index.md index 3f6601d..5c0428a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,8 +16,8 @@ generated declarations, stories, and the package consumer skill. Delivery behavior is owned by package scripts, repository scripts, and GitHub workflows; this directory does not copy those executable contracts. - -## SVC Corpus + +## SVC CLI -Use `svc lookup` when packaged Sustainable Vibe Coding Corpus guidance is relevant, and discover its browse/search/read grammar through `svc lookup --help`. Project documentation outside this marked block remains Consumer-owned. +Use `svc --help` and the installed SVC Skills for framework guidance. Project documentation outside this marked block remains Consumer-owned. diff --git a/packages/web/MIGRATION.md b/packages/web/MIGRATION.md index 1e30733..580457e 100644 --- a/packages/web/MIGRATION.md +++ b/packages/web/MIGRATION.md @@ -43,7 +43,7 @@ InkDialog 的 pending 继续锁住内部 InkButton、确认、取消、Escape Button pending 的覆盖层改为相邻 spinner；依赖 `ink-button__loading-overlay` 的样式需要移除。Button、带框输入和 Switch 的固定高度改为可增长的最小高度，Switch xs 从 18px 增至至少 24px，两个状态文案共同决定宽度。Dropdown 选中说明、DoubleCheck 普通标题、Image 标题底板和遮罩透明度已改正，Dialog 同样由 Popup 承担内边距，默认宽度上限 640px，窄视口两侧各留 16px；清理相应下游补丁后再复核。 -已知 client-web 调用包括：settings 的 `apply-font('title', 'lg')`；LogsViewer／RecallSearch 的 body-md 和错误背景；JobCard／任务详情／peerCard 的反馈颜色；侧栏、来源内容和设置通知中的 muted；info-base/list 的页面标题与空间。逐处按用途迁移，不能全局机械替换。extension registry 的实际消费位置尚未确认，须在消费者验收中补齐。 +已知 impl-ts 调用包括：settings 的 `apply-font('title', 'lg')`；LogsViewer／RecallSearch 的 body-md 和错误背景；JobCard／任务详情／peerCard 的反馈颜色；侧栏、来源内容和设置通知中的 muted；info-base/list 的页面标题与空间。逐处按用途迁移，不能全局机械替换。extension registry 的实际消费位置尚未确认，须在消费者验收中补齐。 Figma 导入也改变：仅更新已知路径的值，显式提供 releaseType，旧的全量导出包含已删除角色时会失败。维护者应更新发送端或准备只含已知值的提议；具体接收端格式见仓库 Token 生成说明。 @@ -55,8 +55,8 @@ Figma 导入也改变：仅更新已知路径的值，显式提供 releaseType 本节对应 2.0.0 的基础控件、弹层和 schema 编辑契约调整。升级时完成以下迁移并验证真实保存流程。 -- InkButton 默认原生类型改为 button。表单提交写 `nativeType="submit"`；type 仍控制 default/square 外形。client-web 的 info-base/list 和 RecallSearch 搜索按钮依赖旧默认提交行为，需要明确标记。 -- InkJsonEditor 的模型现在包含原始文本和无效 JSON。将直接 JSON.parse 的 computed setter 改为独立字符串草稿，监听 validation；仅在 valid=true 且结果 text 与草稿一致时解析和持久化。client-web 的 peerCard 配置编辑属于这种调用，必须迁移，否则输入中间态会让 setter 抛错。 +- InkButton 默认原生类型改为 button。表单提交写 `nativeType="submit"`；type 仍控制 default/square 外形。impl-ts 的 info-base/list 和 RecallSearch 搜索按钮依赖旧默认提交行为，需要明确标记。 +- InkJsonEditor 的模型现在包含原始文本和无效 JSON。将直接 JSON.parse 的 computed setter 改为独立字符串草稿，监听 validation；仅在 valid=true 且结果 text 与草稿一致时解析和持久化。impl-ts 的 peerCard 配置编辑属于这种调用，必须迁移，否则输入中间态会让 setter 抛错。 - InkPicker 的内置日期选择只在 Confirm 更新 Date，取消不再提交。初始化可用 null；JSON 日期字符串应由消费者转换，InkAutoForm 已提供其内部字符串边界。 - Popup/Scrim 使用原生 dialog。提供 aria-label 或 aria-labelledby；不要依赖旧遮罩 DOM 选择器。scrim=false 保留非模态行为，默认模式由浏览器提供背景隔离、嵌套与焦点管理。 - useOptionalVModel 与内部 optional model 统一：传入非 undefined 的模型由父级控制，父级拒绝更新时显示不会擅自改变。传常量 false 不等于省略模型。 diff --git a/packages/web/README.md b/packages/web/README.md index 5bd85e0..b64864c 100644 --- a/packages/web/README.md +++ b/packages/web/README.md @@ -47,15 +47,15 @@ Sass helper 与 Token 子路径见[样式入口](styles/README.md)。构建 CSS ## 本地源码联调 -以下命令在 UI 源码仓库根执行，要求存在相邻的 client-web checkout，且两个工作区都已按各自指南安装依赖： +以下命令在 UI 源码仓库根执行，要求存在相邻的 impl-ts checkout，且两个工作区都已按各自指南安装依赖： ```bash pnpm generate -pnpm --dir ../client-web dev:ui --ui-source ../ui/packages/web -pnpm --dir ../client-web type-check:ui --ui-source ../ui/packages/web +pnpm --dir ../impl-ts dev:ui --ui-source ../ui/packages/web +pnpm --dir ../impl-ts type-check:ui --ui-source ../ui/packages/web ``` -将 `../ui` 替换为本地实际 checkout 路径。消费者拥有源码映射和 peer 运行时解析；正式构建与 CI 仍使用锁定的发布产物。Token 源变化后需重新生成。完整启动、清理和故障排查见[消费者开发指南](https://github.com/InKCre/client-web/blob/main/docs/40-deployment/development-runtime.md#joint-development-lanes)。 +将 `../ui` 替换为本地实际 checkout 路径。消费者拥有源码映射和 peer 运行时解析；正式构建与 CI 仍使用锁定的发布产物。Token 源变化后需重新生成。完整启动、清理和故障排查见[消费者开发指南](https://github.com/InKCre/impl-ts/blob/main/docs/40-deployment/development-runtime.md#joint-development-lanes)。 ## Agent Skill diff --git a/svc.json b/svc.json index 885a9bf..dff8a28 100644 --- a/svc.json +++ b/svc.json @@ -1,4 +1,3 @@ { - "schema_version": 3, - "corpus_version": "14.0.0" + "schema_version": 4 }