50 lines
2.8 KiB
Markdown
50 lines
2.8 KiB
Markdown
# Artifact Design Doctrine
|
|
|
|
Use this layer when a skill produces user-facing artifacts: HTML reports, Markdown tutorials, review viewers, dashboards, screenshots, tables, slide-like pages, or generated skill overview pages.
|
|
|
|
## Principle
|
|
|
|
Output quality is part of skill quality. A generated skill should not only know what to do; it should also know how its final artifact should read, scan, and hold up under review.
|
|
|
|
The visual system must follow the artifact's purpose. Do not inherit a fixed house style just because a reference skill uses one. For example, Kami's paper-editorial discipline is useful, but its warm parchment background is not a default requirement for Yao-generated artifacts.
|
|
|
|
## What To Borrow From Document Skills
|
|
|
|
- route by artifact type before designing the page
|
|
- extract facts, claims, numbers, actions, and missing inputs before formatting
|
|
- ask one focused question when the artifact lacks a necessary audience, input, or output standard
|
|
- keep prose, layout, and production checks separated
|
|
- verify placeholders, headings, paths, screenshots, and render-critical assumptions before delivery
|
|
|
|
## What To Borrow From Presentation Skills
|
|
|
|
- plan the artifact's role, hierarchy, density, rhythm, and evidence before writing HTML
|
|
- choose a concrete visual direction from the topic, not from a generic AI template
|
|
- use structure, spacing, type, and contrast before decoration
|
|
- split dense content instead of squeezing it into one surface
|
|
- reject generic purple gradients, glass cards, repeated card grids, and decorative screenshots
|
|
|
|
## Content-Led Visual Direction
|
|
|
|
Pick the design system from the work:
|
|
|
|
- high-trust reports: restrained editorial layout, strong hierarchy, compact evidence blocks
|
|
- tutorials: clear progressive sections, success checks, screenshots only when real and necessary
|
|
- dashboards: compact metrics, visible deltas, short explanations, no paragraph-heavy tables
|
|
- review viewers: side-by-side comparison, reviewer-visible evidence, explicit tradeoffs
|
|
- slide-like artifacts: rhythm, section breaks, big claims, controlled density
|
|
|
|
## Non-Negotiables
|
|
|
|
- headings must be specific to the user's domain and outcome
|
|
- tables are used only when comparison is the main job
|
|
- citations and footnotes must not interrupt ordinary reading
|
|
- screenshots and visual evidence must be real, sourceable, and correctly described
|
|
- final HTML must not contain absolute local filesystem paths
|
|
- mobile and narrow-width reading must remain usable
|
|
- design tokens must be named and coherent: type, color, spacing, surface, and emphasis
|
|
|
|
## Reviewer Rule
|
|
|
|
Reviewers should see both the artifact's intended visual direction and the top risks that could make the output feel low quality. If a report looks polished but hides weak headings, bad tables, wrong screenshots, or citation clutter, the skill is not ready.
|