yugoo-design 0.1.2 → 0.2.0

package/payload/overlays/codex/authoring/studio-creators/source/packages/skills-web-app/bundles/design_style/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: design_style
+description: |-
+  - **Capability**: visual direction for a web/mobile product — palette, typography, component language, and one representative UI preview.
+  - **Resolves**: S/T gaps in visual hierarchy, component language, and reviewable interface direction; visible feedback may also add U evidence.
+  - **Candidate when**: the user explicitly asks for visual direction, one representative screen is the smallest useful way to settle a material product decision, or the user has explicitly requested high-fidelity pages and the project has no visual baseline.
+  - **Do not infer**: website, page, or app alone does not make visual work mandatory; an explicit high-fidelity Page request is an output dependency rather than keyword inference.
+  - **Output**: `design_style` panel, generated `DESIGN.md`, generated `tokens.css`, and one representative HTML preview.
+---
+
+# Visual Style
+
+Create a product-specific visual system and prove it on one representative
+screen. This is a design artifact; it is not a substitute for implementing every function.
+
+This Bundle is the project's live visual-language control center, not a
+one-time upstream stage. Every invocation is a focused revision of the same
+persisted facet. Preserve settled decisions and update only the visual
+language the user changed or a concrete Page Design gap requires. It owns
+presentation grammar: semantic hierarchy roles, typography and token scales,
+shell treatment, reusable component patterns and states, the selected icon
+library and semantic icon mapping, and the exact brand assets. It does not
+decide which product Pages exist or which business content belongs on them.
+
+When the main Agent invokes this Bundle to satisfy an explicit Page Design request that has no active visual result, create a complete product-appropriate baseline from current Design evidence and sound defaults. Publish the ordinary Design Style artifacts and panel, and describe the baseline as adjustable. Do not emit a generic wireframe theme, ask the user to choose among arbitrary aesthetics before making progress, or claim user approval without evidence. The main Agent may then continue the already requested Page Design work in the same attached turn.
+
+
+
+## Ownership and tools
+
+`design_style/design_style.json` is the only canonical state. The Producer first
+uses the project-scoped `list` and `read` tools to inspect that state, its owned
+artifacts, and relevant upstream evidence. It uses `write` or `edit` to maintain
+the complete state and representative self-contained HTML preview in its owned
+working copy. Before publication it calls the bundled `design-style.mjs`
+file-mode operations. The script processes project files directly and either
+validates the preview or generates:
+
+- `design_style/DESIGN.md` — semantic handoff for people and coding agents;
+- `design_style/tokens.css` — executable `--ds-*` token projection.
+
+Both projections are generated files. Users edit the structured design controls
+(colors, typography, density, components, intent); the Producer reruns the
+Bundle script and the Host writes both outputs directly. Never create a competing token
+source. Once a preview exists, the terminal publication keeps the complete state
+and existing or repaired HTML together in the Producer working copy. The
+pre-preview plan remains an ordinary visible filesystem state, not a commit.
+The Producer completes the visual work itself. Use `read_skill_resource` for
+this Bundle's reference files.
+
+## Existing design
+
+The saved state is authoritative. On later requests, read the current state and
+owned preview/projections before editing, then decide whether the request needs
+a targeted edit or a genuinely necessary regeneration. Preserve explicit brand
+constraints, unaffected valid decisions, direct artifact references, and
+unchanged preview content. Change only the requested tokens, rationale,
+preview, or assets. Regenerate the complete preview only when the requested
+change invalidates its overall hierarchy or visual language. The working copy must
+retain the complete state and owned artifact set even when `edit` changes only
+one local region.
+
+When `page_design` exists, inspect it as current usage evidence so the visual
+system covers real interface needs without copying its Page map. A concrete
+gap handed back by the main Agent is a focused Style revision: define or refine
+only the missing hierarchy role, component pattern, state, icon mapping, or
+brand asset. Never take ownership of Page HTML and never launch Page Design
+from this Producer. The main Agent may let the user review the Style revision
+and then invoke a fresh Page Design Producer for affected Pages.
+
+For a legacy project whose preview record still contains inline `html`, treat
+those bytes as migration input only. If its referenced preview file is missing,
+write the inline bytes to the stable `design_style/preview_<name>.html` path;
+then remove the inline field before validation. Never publish both forms.
+
+The persisted visual result is the current design, not a draft awaiting promotion.
+User approval alone does not require a confirmation-only rewrite. Revise the
+design when actual changes are requested; validity does not imply user approval.
+When revising legacy state, remove the obsolete `config.is_confirmed` marker
+while preserving the design and unrelated fields. Do not rerun only to remove it.
+
+## Grounding
+
+Use supplied `<design_context>` before inventing content. Relevant evidence
+includes answered structured questions, function modules, key business/user flows,
+research conclusions, roles, constraints, and confirmed visual decisions. Read
+a full artifact only when omitted detail would change the representative screen.
+
+### Mandatory cross-design alignment check
+
+Treat active function modules and confirmed flows as product constraints. Preserve the
+relevant actor, action, state, decision, and outcome. If artifacts conflict,
+surface the concrete conflict; do not hide it behind attractive UI. A preview
+must contain recognizable product language and behavior, but need not cover all
+modules. This is grounding, not coverage. Never invent a generic dashboard, landing page, or content hierarchy that contradicts the existing design.
+Do not default to a dashboard.
+
+## Progressive visual knowledge
+
+Read [reference/artifact-contract.md](reference/artifact-contract.md) before maintaining state, projections or preview HTML. It is the shared output and script contract.
+
+The shared output/CLI contract lives in the reference above; forward-design
+choices remain here. Load visual domain knowledge progressively:
+
+| Resource | Load rule |
+| --- | --- |
+| `reference/aesthetic_index.yaml` | Read once after forming the physical scenario; choose before reading direction detail. |
+| `reference/aesthetics/<id>/DESIGN.md` | Read exactly one selected seed. It is the seed's semantic and token source. |
+| `reference/aesthetics/<id>/tokens.css` | Deterministic compiled sibling. Usually do not read; inspect only to diagnose CSS reproduction. |
+| `reference/quality_rubric.md` | Read once before materializing a new preview or making a substantial redesign. |
+| `reference/post_check.md` | Read after the preview exists, immediately before rendered review. |
+| `reference/motion.md` | Read only when motion intensity is at least 7 or choreography is material. |
+| `assets/icons/_index.md` | Read only when the preview needs bundled icons. |
+
+Never combine multiple seeds in one proposal. An explicit brand/reference may
+justify a bespoke direction without a seed.
+
+## Execution
+
+### 1. Reason before selecting an aesthetic
+
+Privately form one physical-scenario sentence: who uses the product, where and
+when, on what form factor, for how long, and with what attention pattern. This
+is a reasoning input, not an aesthetic property: do **not** put it in a seed,
+`DESIGN.md`, `tokens.css`, or canonical state unless the scenario itself is a
+confirmed product requirement worth recording elsewhere.
+
+Then identify the category's reflexive generic answer and reject it when it
+does not fit. Set design variance, motion intensity, and visual density from
+`0..10` with a short product-specific reason. Read the compact aesthetic index,
+select one direction, and only then read its `DESIGN.md`. Choose the single
+screen where the product's distinctive interaction is clearest.
+
+### 2. Build and save the complete anchor
+
+Build the complete anchor using the installed schema and [shared artifact contract](reference/artifact-contract.md), then generate its projections and author the preview through that contract.
+
+### 3. Materialize the preview
+
+Read `reference/quality_rubric.md`, then prepare one compact, complete responsive
+HTML5 document at `design_style/preview_<name>.html`. Target 8–12 KB and never
+exceed 16 KB. It must prove the product's distinctive hierarchy and primary
+interaction in one representative viewport; compact does not mean a generic
+sidebar, toolbar, stock table, or empty shell. Do not block the first useful
+preview on image search, image generation, animation polish, secondary
+sections, or exhaustive copy.
+
+Keep the complete canonical state, referenced HTML path, and complete HTML
+together in the current working copy. Publication atomically settles the state,
+preview, `DESIGN.md`, and `tokens.css`; do not side-write a competing artifact
+outside the project-scoped tools. When a later review finds a material defect,
+use `edit` for the affected state or HTML region and preserve all unrelated
+content. For a state-only repair, read and retain the existing complete HTML
+unchanged.
+
+- Follow the stylesheet, token and local-dependency requirements in the shared artifact contract.
+- UI icons must be inline SVGs copied from the bundled `assets/icons/` catalog
+  after reading `assets/icons/_index.md`. Never use emoji, bitmap images, icon
+  fonts, or remote icon libraries as interface icons.
+- Use vanilla JS only when interaction demonstrates a material design decision;
+  keep it small and inline: no large datasets, SVG path libraries, or duplicated
+  markup.
+- Add images only when they are real decision inputs. Persist exact local paths
+  and meaningful alt text in `config.images`; a deliberate CSS/SVG placeholder
+  is better than a broken or irrelevant image.
+Use only the documented `--ds-*` names emitted by the deterministic token
+projection; never infer additional aliases from state field names. If the
+compact page already passes the post-check, stop without optional changes.
+The foreground Producer authors and repairs this compact visual system directly.
+Use only the always-emitted token catalog; validator feedback never justifies
+switching to another guessed naming convention.
+
+### 4. Render, validate, repair, and close
+
+Read `reference/post_check.md`, then use `read` on the working-copy preview HTML,
+and inspect product specificity, hierarchy, spacing, color, typography,
+responsiveness, interaction states, and material imagery. Make targeted
+corrections for observed defects and re-render when the visible result changed.
+If rendering is unavailable, inspect the HTML and report that visual review was
+blocked.
+
+Before preview authoring, write the valid canonical visual-system JSON whose
+preview identity is present but whose `html_file` remains null, then generate
+both projections through the file-mode operations above. File polling
+immediately shows the selected direction and tokens; continue in the same
+foreground Producer to author and inspect the preview, then set the direct ref
+only after the validated HTML exists in the WorkingCopy. Do not call
+`design_publish` for this intermediate filesystem state.
+Run the shared contract’s landed-file token and preview checks, repair their diagnostics, then validate and publish the complete artifact set. Return a short summary of persisted output and material fixes.
+
+Treat `DESIGN.md`, `tokens.css`, and preview HTML refs in canonical config as
+the complete Design Style artifact set. When the design changes, explicitly
+remove obsolete preview files from the WorkingCopy before the same publication;
+do not keep obsolete previews for compatibility.
+
+## Failure discipline
+
+- A validator diagnostic names the repair target; fix it instead of guessing a
+  second contract or restarting valid work.
+- Validation and completion feedback stays with the Producer. Preserve
+  valid decisions; never turn an artifact defect into a complete restart.
+- Image failure keeps a deliberate placeholder; it does not restart design.
+- Do not reread resources or loop review without new evidence.
+
+## Close-out and U/S/T
+
+Close only after state, both generated projections, and a usable representative
+preview exist. A coherent system and preview normally add S/T evidence. Add U
+only when visible feedback actually settles scope or intent; never award a
+fixed increment merely because this skill ran. Typical confirmed work adds S
+`+10..+15`, T `+10..+20`; early visual elicitation may add U `+10..+20`.
+After the state, projections, and preview are persisted, report the evidence they add to U/S/T and any material uncertainty that remains.
+
+## Attribution
+
+Sources are recorded in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+That file is attribution, not runtime guidance.

package/payload/overlays/codex/authoring/studio-creators/source/packages/skills-web-app/bundles/design_style/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,58 @@
+# Third-party notices — pilot/design_style skill
+
+Full upstream license texts accompany this notice under `licenses/`:
+`impeccable/LICENSE` (Apache-2.0), `taste-skill/LICENSE` (MIT), and
+`lucide/LICENSE` (upstream ISC and retained constituent notices).
+`licenses/SOURCE.md` records immutable retrieval references. These references
+identify the supplied texts; they do not invent the historical revision of
+the adapted guidance or icons.
+
+The design-style knowledge and icon bundle is an authored synthesis informed by
+the following open-source projects. No third-party exemplar or anti-pattern HTML
+is shipped in the active bundle.
+
+## impeccable / Anthropic frontend-design
+
+- Source: <https://github.com/pbakaus/impeccable>
+- Upstream source: <https://github.com/anthropics/skills/tree/main/skills/frontend-design>
+- License: Apache License 2.0
+- Copyright: 2025–2026 Paul Bakaus; 2025 Anthropic, PBC
+
+The compact quality rubric and aesthetic seed guidance draw on their treatment
+of color/contrast, typography, spatial rhythm, motion, interaction states, and
+common generated-UI failure modes. The material is rewritten for AutoAgent's
+canonical state, `DESIGN.md` / `tokens.css` projections, Chinese/Latin font
+fallbacks, representative-preview workflow, and runtime-neutral tool boundary.
+
+Apache License 2.0: <https://www.apache.org/licenses/LICENSE-2.0>
+
+## taste-skill
+
+- Source: <https://github.com/leonxlnx/taste-skill>
+- License: MIT License
+- Copyright: 2026 Leonxlnx
+
+The pre-selection reasoning uses its design variance, motion intensity, and
+visual density dials, plus its emphasis on rejecting generic generator reflexes.
+React/Next.js/Tailwind-specific machinery and large effect catalogs are not
+included.
+
+## Lucide icons
+
+- Source: <https://github.com/lucide-icons/lucide>
+- License: ISC License
+
+The SVGs under `assets/icons/` are derived from Lucide and adjusted to the
+bundle's naming and sizing conventions.
+
+## Current authored layout
+
+- `reference/aesthetic_index.yaml` is a lightweight pre-selection index.
+- `reference/aesthetics/<id>/DESIGN.md` is the maintained seed source.
+- each sibling `tokens.css` is deterministically compiled from that seed.
+- `reference/quality_rubric.md`, `post_check.md`, and `motion.md` are bounded
+  phase-specific guidance.
+
+The previous copied exemplar/anti-pattern HTML and adapted `_base.css` have been
+removed from the active bundle; their provenance remains available in Git
+history.

package/payload/overlays/codex/authoring/studio-creators/source/packages/skills-web-app/bundles/design_style/reference/artifact-contract.md

@@ -0,0 +1,195 @@
+# Design Style output contract
+
+Shared by forward design and source reconstruction. The installed schema and validation define the state. This document defines artifact representation and file operations, not how to choose a new visual direction.
+
+## Visual authority
+
+`config.hierarchy` names reusable visual roles, not business priorities.
+`config.component_patterns` records reusable anatomy, variants, and states;
+it is a design contract, not a runtime component library or HTML template.
+`config.iconography` records the chosen library and one coherent size/stroke
+grammar, while `config.icons` maps stable semantic IDs to exact SVG markup.
+When the SVG comes from this Bundle, retain its optional Bundle-relative
+`asset` provenance such as `assets/icons/search.svg`; the JSON remains the
+exact handoff authority and Page workers inline those bytes into standalone
+artifacts. Neither SVG markup nor the library choice is emitted into CSS.
+The JSON and generated `DESIGN.md` retain those decisions. `tokens.css` carries
+only directly consumable values such as color, type, spacing, radius, icon
+size, and stroke width; it never embeds SVG source or the icon-library choice.
+If no brand mark is accepted, use the brand name as a text wordmark rather
+than inventing a Page-local mark.
+
+## State and projections
+
+Use the following shape. Required groups for a completed proposal are marked
+`REQUIRED`; optional fields are included only when they carry a real decision.
+Example values and the listed aesthetic vocabulary illustrate representation;
+they are not defaults or source facts. During restoration use the actual source
+values and vocabulary, not this example's font sizes, icon library or layout.
+
+```json
+{
+  "skill_name": "design_style",
+  "epoch": 0,
+  "config": {
+    "theme": "REQUIRED: one-line direction label",
+    "layout": {
+      "mode": "sidebar | topbar | bottom-nav | dashboard | minimal",
+      "sidebar": {"position": "left | right", "style": "fixed | collapsible"},
+      "content_width": "narrow | medium | wide | full",
+      "density": "compact | comfortable | spacious"
+    },
+    "colors": {
+      "primary": "#RRGGBB", "primaryLight": "#RRGGBB",
+      "primaryDark": "#RRGGBB", "secondary": "#RRGGBB",
+      "accent": "#RRGGBB", "background": "#RRGGBB",
+      "surface": "#RRGGBB", "text": "#RRGGBB",
+      "textSecondary": "#RRGGBB", "border": "#RRGGBB"
+    },
+    "semantic_colors": {
+      "success": "#RRGGBB", "warning": "#RRGGBB",
+      "error": "#RRGGBB", "info": "#RRGGBB"
+    },
+    "typography": {
+      "headingFont": "CSS font stack", "bodyFont": "CSS font stack",
+      "monoFont": "CSS font stack", "baseFontSize": "14px",
+      "headingWeight": "600", "lineHeight": "1.5",
+      "fontSizeXs": "12px", "fontSizeSm": "13px",
+      "fontSizeLg": "16px", "fontSizeXl": "20px", "fontSize2xl": "28px"
+    },
+    "hierarchy": {
+      "page_title": "primary screen identity",
+      "section_title": "major content grouping",
+      "supporting_text": "secondary explanation"
+    },
+    "components": {
+      "borderRadius": "8px", "shadowDepth": "none | subtle | medium | deep",
+      "buttonStyle": "filled | outlined | soft",
+      "inputStyle": "bordered | filled | underlined",
+      "cardStyle": "flat | elevated"
+    },
+    "component_patterns": {
+      "primary_navigation": {
+        "description": "stable application navigation treatment",
+        "anatomy": ["icon", "label"],
+        "variants": ["default", "compact"],
+        "states": ["default", "hover", "active", "focus"]
+      }
+    },
+    "iconography": {
+      "library": "bundled library name", "style": "outline",
+      "view_box": "0 0 24 24", "stroke_width": "1.75",
+      "linecap": "round", "linejoin": "round",
+      "size_sm": "16px", "size_md": "20px", "size_lg": "24px"
+    },
+    "icons": {
+      "navigation_search": {
+        "label": "Search", "svg": "<svg ...>...</svg>",
+        "asset": "assets/icons/search.svg"
+      }
+    },
+    "preview_page": {
+      "name": "REQUIRED: stable_snake_case_name",
+      "title": "REQUIRED: user-facing title",
+      "rationale": "REQUIRED: why this screen proves the direction",
+      "html_file": null
+    },
+    "notes": "concise product-specific conclusion, not hidden reasoning",
+    "aesthetic": {
+      "vocabulary": "selected seed id or bespoke",
+      "mood": "short phrase", "copy_register": "voice rule",
+      "lighting_hints": "optional imagery guidance"
+    },
+    "motion": {
+      "duration_fast": "150ms", "duration_normal": "300ms",
+      "duration_slow": "500ms", "ease_standard": "cubic-bezier(...)"
+    },
+    "spacing": {"base": "4px", "scale": ["4px", "8px", "12px", "16px"]},
+    "elevation": {"dropdown": 10, "sticky_nav": 20, "modal": 50, "tooltip": 70},
+    "breakpoints": {"sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px"},
+    "dark_mode": {"colors": {"background": "#RRGGBB"}},
+    "brand": {"name": "", "name_en": "", "tagline": ""},
+    "images": {
+      "slot_name": {
+        "source": "ai | pexels | iqs | external", "path": "images/exact-file.ext",
+        "prompt": "", "url": null, "photo_id": null, "photographer": null,
+        "photographer_url": null, "alt": "meaningful text",
+        "width": null, "height": null, "avg_color": "#RRGGBB"
+      }
+    },
+    "preview_pages": []
+  }
+}
+```
+
+For a text-only brand, omit both `brand.mark_id` and `brand.mark_svg`. For an
+accepted SVG mark, supply both together: a stable `mark_id` and the exact
+complete local `mark_svg` bytes. An existing raster mark uses `brand.logo_image`
+instead; a missing SVG is not permission to replace its identity.
+
+`colors`, `semantic_colors`, `typography`, `hierarchy`, `components`,
+`component_patterns`, `iconography`, `layout`, and `preview_page` are REQUIRED
+for a new completed proposal. Add only the semantic icon mappings actually
+needed by current Style previews or Page evidence; do not build an exhaustive
+catalog. `epoch` is preserved from
+existing state. Preview HTML is a direct Bundle artifact, never an embedded
+canonical JSON field. Use only project-relative `design_style/...` artifact pointers, never host
+workspace prefixes or old flat paths.
+
+After coherent tokens and the preview identity are chosen, write the complete
+state whose `html_file` is null. Call `run_skill_script` twice with
+`path: "design-style.mjs"`, `args` set to `["render-design-md"]` and
+`["render-tokens-css"]`, `input_file: "design_style/design_style.json"`, and
+`output_file` set to `design_style/DESIGN.md` and `design_style/tokens.css`
+respectively. The Host writes both projections directly, so their bytes never
+pass through model context. This is an ordinary live filesystem update for
+panel polling, not a publication or Git boundary.
+Before authoring, call `design_focus_artifact` with
+`artifact_kind: "design_style_preview"`, `artifact_id` equal to
+`preview_page.name`, and `artifact_file` equal to the exact
+`design_style/preview_<name>.html` path, so panel activity binds to that one
+artifact. Then author `design_style/preview_<name>.html` and update
+`html_file` to that exact project-relative path in the same working copy. Run
+`design_validate` against the working copy. Field-level validation errors are
+authoritative; correct the named working-copy field or artifact and validate
+again.
+
+## Preview file
+
+One complete HTML5 document at `design_style/preview_<name>.html`; its canonical reference is project-relative and accepted only after the actual file passes validation.
+
+- In `<head>`, link `<link rel="stylesheet" href="./tokens.css">`.
+- Consume at least five `var(--ds-*)` values and use them for canonical palette
+  roles, font families, type hierarchy, radius, shadow, density, and content
+  width. Route color, type, spacing, radius, and elevation through the emitted
+  scale; only structural dimensions and positions remain local.
+- Do not declare `--ds-*` in HTML and do not add token fallback values. Changes
+  belong in canonical state; the platform regenerates `tokens.css`.
+- Keep scripts/assets local. No CDN, expiring URL, fabricated metric, broken
+  icon, or generic filler section.
+
+## Original local images
+
+An existing raster brand uses `config.brand.logo_image` with its project-relative `path`, `source: "external"` and meaningful `alt`; omit SVG-only `mark_id`/`mark_svg`. Other local images use `config.images`. Record actual scope in existing descriptions. Use prepared original bytes, not transcribed base64 or invented replacements. In preview HTML, use plain `img src` relative to that HTML for local PNG/JPEG/WebP. The panel embeds those bytes; CSS background assets, fonts and responsive picture sets are not automatically imported. Report material unsupported presentation.
+
+## Landed-file validation
+
+Immediately before publication, check the actual generated stylesheet with
+`run_skill_script`, `path: "design-style.mjs"`,
+`args: ["validate-tokens-file"]`, `input_file: "design_style/tokens.css"`,
+and `input_context: {state: <current complete state>}`. This reads the landed
+file, not an in-memory substitute. Repair mismatches by regenerating from the
+current canonical JSON; preview validation alone does not check that file.
+Then call `run_skill_script` with
+`path: "design-style.mjs"`, `args: ["validate-preview-file"]`, `input_file`
+equal to the preview HTML path, and `input_context` containing
+the current `state` and exact `preview_file` path. It returns diagnostics only;
+repair them, call `design_validate({outcome:"complete"})`,
+then call `design_publish({action:"complete"})` only when both checks pass. The
+Host completion gate independently rejects a `complete` whose
+`config.preview_page.html_file` is null or empty, so the accepted preview ref is
+required before the terminal publication settles; a milestone plan with a null
+`html_file` stays an ordinary working-copy state, never a `complete` commit.
+If the same diagnostic repeats without file/state progress, stop
+editing and report the exact blocker; never restart the complete visual design.
+Return a short summary of persisted output and material fixes.

package/payload/overlays/codex/authoring/studio-creators/source/packages/skills-web-app/bundles/design_style/schema.yaml

@@ -0,0 +1,177 @@
+# design_style Design Files data contract (write-time validation).
+# Adapted from the sdk-pilot visual model for DSH file-backed previews. Preview
+# records are closed so historical inline HTML cannot become a second authority.
+#
+# Agent writes settle the complete state and preview HTML atomically through
+# ordinary WorkingCopy publication. All config fields are optional with defaults so
+# lean stage-2 payloads stay valid.
+#
+# Script invariants owned by scripts/design-style.mjs (not expressible here):
+# theme <= 80 chars single line; colors/semantic_colors/dark_mode.colors must
+# be valid hex or recognised CSS named colors; design content fields must be
+# nested inside `config`, never at the top level.
+#
+# `nullable: true` marks fields the Pydantic model types `... | None`;
+# the write-time validator accepts null for them.
+type: object
+properties:
+  skill_name: { knowledge: { role: metadata }, type: string }
+  epoch: { knowledge: { role: metadata }, type: number }
+  config:
+    type: object
+    knowledge: { role: content, granularity: container, label: 设计风格配置 }
+    properties:
+      theme: { knowledge: { role: content, granularity: property }, type: string } # visual-direction label, <=80 chars, single line
+      layout:
+        type: object
+        knowledge: { role: content, granularity: unit, label: 布局规范 }
+        properties:
+          mode: { type: enum, values: [sidebar, topbar, bottom-nav, dashboard, minimal] }  # default sidebar
+          sidebar:
+            type: object
+            nullable: true
+            properties:
+              position: { type: string }   # left | right
+              style: { type: string }      # fixed | collapsible
+          content_width: { type: enum, values: [narrow, medium, wide, full] }  # default wide
+          density: { type: enum, values: [compact, comfortable, spacious] }    # default comfortable
+      colors: { knowledge: { role: content, granularity: unit, label: 基础配色 }, type: map, value: { type: string } }
+      typography: { knowledge: { role: content, granularity: unit, label: 字体与排版 }, type: map, value: { type: string } }
+      components: { knowledge: { role: content, granularity: unit, label: 通用组件样式 }, type: map, value: { type: string } }
+      hierarchy: { knowledge: { role: content, granularity: unit, label: 文本层级 }, type: map, value: { type: string } }
+      component_patterns:
+        type: map
+        value:
+          type: object
+          knowledge: { role: content, granularity: unit, label: 组件模式 }
+          additional_properties: false
+          required: [description]
+          properties:
+            description: { type: string }
+            anatomy: { type: array, items: { type: string } }
+            variants: { type: array, items: { type: string } }
+            states: { type: array, items: { type: string } }
+      iconography:
+        type: object
+        knowledge: { role: content, granularity: unit, label: 图标规范 }
+        additional_properties: false
+        properties:
+          library: { type: string }
+          style: { type: string }
+          view_box: { type: string }
+          stroke_width: { type: string }
+          linecap: { type: string }
+          linejoin: { type: string }
+          size_sm: { type: string }
+          size_md: { type: string }
+          size_lg: { type: string }
+      icons:
+        type: map
+        value:
+          type: object
+          knowledge: { role: content, granularity: unit, label: 图标 }
+          additional_properties: false
+          required: [label, svg]
+          properties:
+            label: { type: string }
+            svg: { type: string }
+            asset: { type: string }
+      semantic_colors: { knowledge: { role: content, granularity: unit, label: 状态配色 }, type: map, value: { type: string } }
+      dark_mode: { knowledge: { role: content, granularity: unit, label: 深色模式 }, type: map, nullable: true, value: { type: map, value: { type: string } } }
+      preview_page:
+        type: object
+        knowledge: { role: content, granularity: unit, label: 风格预览 }
+        nullable: true
+        additional_properties: false
+        properties:
+          name: { type: string }
+          title: { type: string }
+          rationale: { type: string }
+          html_file: { type: string, nullable: true }   # path under design_files/design_style/
+      notes: { knowledge: { role: content, granularity: unit, label: 来源与补充说明 }, type: string }
+      motion:
+        type: object
+        knowledge: { role: content, granularity: unit, label: 动效规范 }
+        properties:
+          duration_fast: { type: string }    # default 150ms
+          duration_normal: { type: string }  # default 300ms
+          duration_slow: { type: string }    # default 500ms
+          ease_standard: { type: string }    # default cubic-bezier(0.16, 1, 0.3, 1)
+          ease_in: { type: string }          # default cubic-bezier(0.7, 0, 0.84, 0)
+          ease_out: { type: string }         # default cubic-bezier(0.16, 1, 0.3, 1)
+          ease_spring: { type: string }      # default cubic-bezier(0.5, 1.5, 0.5, 1)
+      spacing:
+        type: object
+        knowledge: { role: content, granularity: unit, label: 间距规范 }
+        properties:
+          base: { type: string }             # default 4px; numbers normalized to px at the boundary
+          scale: { type: array, items: { type: string } }
+      elevation:
+        type: object
+        knowledge: { role: content, granularity: unit, label: 叠放层级 }
+        properties:
+          dropdown: { type: number }         # default 10
+          sticky_nav: { type: number }       # default 20
+          drawer: { type: number }           # default 30
+          modal_backdrop: { type: number }   # default 40
+          modal: { type: number }            # default 50
+          toast: { type: number }            # default 60
+          tooltip: { type: number }          # default 70
+      breakpoints:
+        type: object
+        knowledge: { role: content, granularity: unit, label: 响应式断点 }
+        properties:
+          sm: { type: string }   # default 640px
+          md: { type: string }   # default 768px
+          lg: { type: string }   # default 1024px
+          xl: { type: string }   # default 1280px
+          xxl: { type: string }  # default 1536px
+      images:
+        type: map
+        value:
+          type: object
+          knowledge: { role: content, granularity: unit, label: 图片素材 }
+          properties:
+            source: { type: enum, values: [ai, pexels, iqs, external] }  # default ai
+            path: { type: string, nullable: true }
+            prompt: { type: string, nullable: true }
+            url: { type: string, nullable: true }
+            photo_id: { type: string, nullable: true }
+            photographer: { type: string, nullable: true }
+            photographer_url: { type: string, nullable: true }
+            alt: { type: string }
+            width: { type: number, nullable: true }
+            height: { type: number, nullable: true }
+            avg_color: { type: string, nullable: true }
+      brand:
+        type: object
+        knowledge: { role: content, granularity: unit, label: 品牌设定 }
+        nullable: true
+        properties:
+          name: { type: string }
+          name_en: { type: string }
+          tagline: { type: string }
+          mark_id: { type: string }
+          wordmark_svg: { type: string, nullable: true }   # inline SVG markup
+          mark_svg: { type: string, nullable: true }       # inline SVG markup
+          logo_image: { type: object, nullable: true }     # ImageRef shape, as `images` values
+      aesthetic:
+        type: object
+        knowledge: { role: content, granularity: unit, label: 视觉气质 }
+        nullable: true
+        properties:
+          vocabulary: { type: string }      # canonical key, e.g. studio_noir
+          mood: { type: string }
+          copy_register: { type: string }
+          lighting_hints: { type: string }
+      preview_pages:
+        type: array
+        items:
+          type: object
+          knowledge: { role: content, granularity: unit }
+          additional_properties: false
+          properties:
+            name: { type: string }
+            title: { type: string }
+            rationale: { type: string }
+            html_file: { type: string, nullable: true }