# Artifact Templates

Use these templates as the default artifact shapes for Da Vinci.

Keep headings stable unless the project requires a different schema.

## `brainstorm.md`

Use this structure:

```md
# Brainstorm

## Inputs
- Raw user ideas
- Repeated themes

## Product Direction
- Stable goals
- Open questions

## Candidate Pages
- Candidate page list

## Candidate Flows
- Candidate user flows

## Risks And Unknowns
- Ambiguities
- Conflicts
- Deferred ideas
```

Use this artifact only when ideas are still being synthesized.

## `project-inventory.md`

Use this structure:

```md
# Project Inventory

## Current Product
- Product summary

## Routes And Pages
- Route
- Page purpose

## UI Regions
- Shared layout regions
- Repeated page patterns

## Technical Constraints
- Existing stack
- Existing design system

## Redesign Impact
- Preserve
- Replace
- Review later
```

Use this artifact when redesign starts from an existing codebase.

## `design-brief.md`

Use this structure:

```md
# Design Brief

## Product Form Factor
- desktop software
- web app
- tablet
- mobile app

## Visual Direction
- tone
- density
- visual references

## Brand Constraints
- existing brand
- color direction
- typography constraints

## Layout Priorities
- desktop-first or mobile-first
- workspace density
- responsiveness expectations

## Notes
- explicit user preferences
- inferred preferences
```

Use this artifact whenever the project is new or the design direction is not obvious from the existing product.

## `design-registry.md`

Use this structure:

```md
# Design Registry

## Active Design Sources
- `.pen` file path
- status
- purpose

## Preferred Design Source
- Which `.pen` file is authoritative

## Historical Or Secondary Sources
- Legacy files
- Alternate explorations

## Notes
- Why a source is active
- Whether a source is safe to iterate
```

Use this artifact whenever a project can have one or more Pencil sources.

## `page-map.md`

Use this structure:

```md
# Page Map

## Canonical Pages
- Page name
- Route or identifier
- Purpose

## States Per Page
- Empty
- Loading
- Success
- Error
- Restricted

## Shared Sections
- Header
- Sidebar
- Footer
- Shared workspace regions

## Page Priority
- Core pages
- Supporting pages
```

Use this artifact for every mode. It is the canonical page list.

## `proposal.md`

Use this structure:

```md
# Proposal

## Change
- Name:
- Owner:
- Date:

## Goal
- What this change must achieve

## Non-Goals
- What this change will not cover

## User Value
- Why this matters

## Scope
- Pages
- Flows
- Integrations

## Risks
- Security
- Migration
- Delivery

## Success Criteria
- Observable outcomes
```

## `specs/<capability>/spec.md`

Use this structure:

```md
# Spec

## Capability
- Name

## Behavior
- Core behavior rules

## States
- Empty
- Loading
- Success
- Error
- Restricted

## Inputs
- User inputs
- External inputs

## Outputs
- User-visible results
- System-visible results

## Acceptance
- Clear testable conditions

## Edge Cases
- Failure paths
- Boundary conditions
```

Write behavior in direct, testable language.

## `design.md`

Use this structure:

```md
# Design

## Page Map
- Pages and sections

## Interaction Model
- Primary actions
- Secondary actions
- State transitions

## Layout Strategy
- Major regions
- Responsive notes

## Component Strategy
- Reusable blocks
- Page-specific blocks

## Content Notes
- Key text
- Priority order

## Open Questions
- Unresolved design decisions
```

## `pencil-design.md`

Use this structure:

```md
# Pencil Design

## Source
- `.pen` file path
- Active pages

## Page Mapping
- Requirement -> Pencil page

## Screens
- Screen name
- Purpose
- Notes

## States Represented
- Which states are drawn
- Which states still need design coverage

## Screenshots
- Reference image paths or exported nodes

## Implementation Notes
- Important layout or styling constraints to preserve in code
```

## `tasks.md`

Use this structure:

```md
# Tasks

## 1. Setup
- [ ] Project or page setup

## 2. UI Structure
- [ ] Implement major sections from Pencil

## 3. Behavior
- [ ] Implement states and interactions from spec

## 4. Integration
- [ ] Wire required data or services

## 5. Verification
- [ ] Check requirement coverage
- [ ] Check Pencil coverage
```

Prefer top-level task groups. They are required for execution checkpoints.

## `pencil-bindings.md`

Use this structure:

```md
# Pencil Bindings

## Source
- `.pen` file path

## Bindings
- implementation page or route -> Pencil page or screen

## Shared Bindings
- shared layout or component -> Pencil region

## Notes
- intentional deviations
- pages without Pencil coverage yet
```

Use this artifact whenever implementation must trace back to Pencil pages.

## `verification.md`

Use this structure:

```md
# Verification

## Requirement Coverage
- Covered items
- Missing items

## Pencil Coverage
- Matched sections
- Design drift

## Behavior Drift
- Scope expansions
- Missing states

## Outcome
- PASS / WARN / BLOCK
- Next action
```