admin
5afeb6b78a
一、④段整套同步（用户选候选 A）
- 新增 `references/stage-proto-doc/assets/产品文档模板.html`（16 KB／247 行，从备份拷、转 LF）。
- ④段 SKILL.md 换成备份 15:28 那版，并按模板口径改齐：
· 「产品文档框架」从「四块＋一附录」改成**六节** —— 页面结构／功能清单／使用场景／操作流程／
跨页与界面状态／待确认与偏离；与模板同构，⛔ 不从空白页重写结构。
· 编号从 R/S/F 改成 **P 页面／S 场景／F 功能／J 二级功能**，各自唯一、按展示顺序通排。
· 保留旧版有价值的要求：每项功能补齐 做什么／入口在哪／输入边界／异常与恢复；重点功能三处标红；
横向流程图每步写清页面／功能／操作／完成判据。
· 完成标准「七节」→「六节」，自查清单同步换掉「需求」那批条目，补模板与配图两条。
· 路径 `designs/<项目>/` → `docs/pm/<项目>/ui/`（2 处）。
· 补回本机那条「每份产出文档开头都要有一张图」的引用（指向主 skill，段内不复述）。
- 主 skill 同步：四段结构表④行、④段沿革、画图小节（④段画页面结构图 ＋ 用户路径）。
二、open-design 移到技能根（用户选候选 A）
- `git mv product-planning/references/stage-delivery/assets/open-design → open-design/`（4178 文件）。
- `.gitignore` 白名单加 `!/open-design/` —— 否则移出去就不再纳入版本控制。
- 引用改 11 处：路径形态 `assets/open-design/...` → `<技能根>/open-design/...`；
「随段携带的自带件」改称「同根技能」；「路径怎么找」那条改成自带件（段内相对路径）与
同根技能（`<技能根>/<技能名>/`）两类分开写。
- open-design 自己的 ATTRIBUTION.md 两处同步（它现在与 oil-ui-pro 同层）。
- 副作用（有益）：命名闸门读数由 2063 降到 225 —— 此前它把 open-design 里 919 个第三方 md
当成规则一起扫了；现在只扫本包 23 个 md。已确认④段的 H1 与 4a/4b/4c 子步仍在检查范围内。
三、验收
- check_naming.py --ws E:/ProgramData/AIProject/contentm_agent ＝ 通过 225 / 失败 0 / 提示 27。
- 活文件里 `assets/open-design` 残留 0；工作区 CRLF 文件 0。
107 lines
6.2 KiB
Markdown
107 lines
6.2 KiB
Markdown
# Craft references
|
|
|
|
Brand-agnostic craft knowledge. Each file is a small, dense rulebook on one
|
|
dimension of professional UI craft (typography, color, motion, …). Skills
|
|
opt into the references they need; the daemon injects only the requested
|
|
ones into the system prompt above the active skill body.
|
|
|
|
## Why a fourth axis next to skills, templates, and design systems
|
|
|
|
| Axis | Scope | Example |
|
|
|---|---|---|
|
|
| `skills/` | Functional capabilities invoked while doing work | `design-brief`, `brand-extract`, `imagegen` |
|
|
| `design-templates/` | Packaged artifact shapes | `saas-landing`, `dashboard`, `pricing-page` |
|
|
| `design-systems/` | Brand package: prose, token contract, and optional rich resources | `linear-app`, `apple`, `notion` |
|
|
| `craft/` | **Universal** craft knowledge — true regardless of brand | letter-spacing rules, accent-overuse caps, anti-AI-slop |
|
|
|
|
`DESIGN.md` tells the agent which colors and fonts a brand uses. `craft/`
|
|
tells the agent the universal rules a competent designer applies on top —
|
|
e.g. ALL CAPS always needs ≥0.06em tracking, regardless of the brand.
|
|
|
|
## How a skill opts in
|
|
|
|
Add an `od.craft.requires` array to the skill's front-matter. Only the
|
|
listed sections are injected, so a skill that needs only typography pays
|
|
no token cost for color/motion content.
|
|
|
|
```yaml
|
|
od:
|
|
craft:
|
|
requires: [typography, color, anti-ai-slop]
|
|
```
|
|
|
|
Use the layered stack for editorial skills that require authored hierarchy
|
|
and sustained reading behavior:
|
|
|
|
```yaml
|
|
od:
|
|
craft:
|
|
requires: [typography, typography-hierarchy, typography-hierarchy-editorial]
|
|
```
|
|
|
|
Allowed shipped values match the file names in this directory minus the `.md`
|
|
extension. The runtime skips an absent file for compatibility, but repository
|
|
authoring does not silently accept arbitrary values.
|
|
|
|
Run `pnpm lint:craft` after adding or changing `od.craft.requires`. The
|
|
repository guard reports unresolved slugs with their manifest paths, so typos
|
|
cannot silently drop a craft section from the runtime prompt. If a slug is an
|
|
intentional forward reference, list it in `craft/FUTURE_SECTIONS.md` until the
|
|
matching `craft/<slug>.md` file ships.
|
|
|
|
### Runtime compatibility and authoring failures
|
|
|
|
The loader remains tolerant because externally installed or older bundles may
|
|
reference a section that is unavailable in the current resource set. A missing
|
|
optional paragraph must not make an otherwise usable runtime bundle fail.
|
|
|
|
Checked-in content has a stronger contract: `pnpm lint:craft` and
|
|
`pnpm guard` fail on malformed slugs and unresolved references. A deliberate
|
|
forward reference is valid only when it is listed in
|
|
`craft/FUTURE_SECTIONS.md`; this makes planned work explicit while preserving
|
|
the runtime compatibility behavior.
|
|
|
|
Note for skill authors arriving from older guidance: an earlier draft
|
|
used `motion` as the future-slug placeholder. The shipped equivalent
|
|
today is `animation-discipline`. Use that one if your skill emits
|
|
motion.
|
|
|
|
### Enforcement levels
|
|
|
|
Craft files mix auto-checked rules and guidance.
|
|
|
|
- **Auto-checked.** Rules wired into `apps/daemon/src/lint-artifact.ts` — currently the P0 list in `anti-ai-slop.md` (Tailwind-indigo accent, two-stop hero gradients, emoji-as-icons, etc.). The linter reports these as findings back to the UI (for P0/P1 badges) and to the agent (as a system reminder for self-correction). Artifact persistence is not currently hard-blocked on P0 hits.
|
|
- **Guidance.** The rest. The agent reads the rules, reviewers apply them, the linter doesn't check them.
|
|
|
|
A purely behavioral craft file (state-coverage, animation-discipline) is guidance unless a specific rule is later promoted into `lint-artifact.ts`.
|
|
|
|
## Files
|
|
|
|
| File | Section name | When to require |
|
|
|---|---|---|
|
|
| `typography.md` | `typography` | Any skill that emits typed content (~all skills) |
|
|
| `typography-hierarchy.md` | `typography-hierarchy` | Any skill that emits typed content where hierarchy must feel authored, not assembled — especially surfaces with a strong entry point, varied levels, or intentional rhythm. Compose with `typography`. |
|
|
| `typography-hierarchy-editorial.md` | `typography-hierarchy-editorial` | Skills whose primary artifact is a sustained reading surface: `blog-post`, `docs-page`, `digital-eguide`. Requires `typography` + `typography-hierarchy`. |
|
|
| `color.md` | `color` | Any skill that emits styled output (~all skills) |
|
|
| `anti-ai-slop.md` | `anti-ai-slop` | Marketing pages, landing pages, decks |
|
|
| `state-coverage.md` | `state-coverage` | Any skill with stateful UI (dashboards, mobile apps, forms, list/table views) |
|
|
| `animation-discipline.md` | `animation-discipline` | Any skill that ships motion: mobile apps, multi-screen flows, gamified UI, transitions, microinteractions |
|
|
| `accessibility-baseline.md` | `accessibility-baseline` | Any skill that ships interactive UI: dashboards, forms, mobile flows, anything with focus/labels/keyboard paths |
|
|
| `rtl-and-bidi.md` | `rtl-and-bidi` | Any skill that ships localized text or layout: blogs, docs, financial tables, mobile apps, anything that may render Arabic / Hebrew / Persian |
|
|
| `form-validation.md` | `form-validation` | Any skill whose primary artifact contains an interactive form: lead capture, sign-in, signup, settings, multi-step intake |
|
|
| `laws-of-ux.md` | `laws-of-ux` | Any skill whose composition decisions hit named cognitive limits: pricing pages (Hick's, Choice Overload, Von Restorff), dashboards (Pareto, Selective Attention, Working Memory), onboarding (Goal-Gradient, Zeigarnik, Peak-End), modals (Fitts's, Tesler's). Sibling axis to the rendering-rule files above — covers what to compose, not how to render. |
|
|
|
|
**Partial-stateful skills.** A skill that's mostly static but contains an embedded form, data table, or query surface should opt in. State-coverage rules apply to the stateful component, not the whole page.
|
|
|
|
Planned-but-unshipped slugs are recorded in
|
|
[`FUTURE_SECTIONS.md`](FUTURE_SECTIONS.md); do not hard-code a second future
|
|
list here.
|
|
|
|
## Attribution
|
|
|
|
Craft content is adapted from the MIT-licensed
|
|
[refero_skill](https://github.com/referodesign/refero_skill) project
|
|
(© Refero Design), with edits to fit OpenDesign's house style and link
|
|
back to OD's design tokens (`var(--accent)` etc.) instead of generic
|
|
Tailwind hex values.
|