---
schema_version: 1
id: RAC-KTQ63DX03EG6
type: requirement
---
# RAC v0.6.3 — Design Artifacts

## Context

RAC currently supports multiple first-class product knowledge artifact types:

- Requirements
- Decisions
- Roadmaps
- Prompts

v0.6.x expands RAC's artifact vocabulary before v0.7.x introduces cross-artifact relationships.

The next artifact type to formalize is the Design artifact.

This is needed before v0.8.x, where RAC Explorer introduces a TUI intended to improve adoption and usability for less technical Product Managers.

Building a TUI creates durable product knowledge that is not always cleanly represented as a Requirement, Decision, Roadmap, or Prompt.

Examples include:

- Interaction models
- Navigation patterns
- Visual language
- Theme guidance
- Style guidance
- Accessibility expectations
- Keyboard shortcut conventions
- Layout principles
- Technical constraints
- Component behavior
- Open design questions

These are not work-management artifacts.

They are design knowledge artifacts.

v0.6.3 introduces Design artifacts as first-class RAC artifacts so that UX, interaction, and interface design knowledge can be structured, validated, inspected, improved, and versioned alongside other product knowledge.

---

## Problem

Design knowledge is often spread across:

- Figma files
- screenshots
- notes
- Slack threads
- design reviews
- implementation comments
- product documents
- ad hoc Markdown files

This makes it difficult to understand:

- why an interface behaves a certain way
- what constraints shaped the design
- what user need the design serves
- which alternatives were considered
- what accessibility or style rules apply
- what questions remain unresolved

For the RAC Explorer / TUI work, this becomes especially important.

The TUI needs consistent design guidance around:

- onboarding
- command entry
- artifact browsing
- search
- navigation
- empty states
- error states
- keyboard behavior
- visual hierarchy
- theme and style choices

RAC needs a way to capture this design knowledge without turning into a design tool, component library, or project-management system.

---

## Goals

Introduce Design artifacts as a supported RAC artifact type.

Support Design artifacts across existing RAC commands:

- `rac schema`
- `rac inspect`
- `rac validate`
- `rac stats`
- `rac improve`

while remaining:

- Markdown-first
- File-first
- AI-optional
- Deterministic
- Read-only except for stdout template generation
- Viewer-agnostic
- Focused on knowledge, not design execution

---

## Design Artifact Schema

### Required Sections

- Context
- User Need
- Design
- Constraints

### Recommended Sections

- Rationale
- Alternatives
- Accessibility
- Style Guidance
- Open Questions

### Optional Sections

- Related Requirements
- Related Decisions
- Related Roadmaps
- Related Prompts

---

## Requirements

### REQ-001 — Design Artifact Support

RAC shall support Design artifacts as a first-class artifact type.

Design artifacts shall be registered in `ArtifactSpec`.

Design support shall reuse the existing artifact architecture rather than introducing design-specific engines.

---

### REQ-002 — Design Schema Definition

The Design `ArtifactSpec` shall define:

- Required sections
- Recommended sections
- Optional sections
- Section descriptions
- Section guidance
- Schema metadata, where applicable

Design sections shall be defined as:

Required:

- Context
- User Need
- Design
- Constraints

Recommended:

- Rationale
- Alternatives
- Accessibility
- Style Guidance
- Open Questions

Optional:

- Related Requirements
- Related Decisions
- Related Roadmaps
- Related Prompts

---

### REQ-003 — Design Schema Reference

`rac schema --list` shall include:

```text
design
```

`rac schema design` shall display the Design schema.

`rac schema design --json` shall expose:

- type
- required sections
- recommended sections
- optional sections
- descriptions
- guidance
- metadata

---

### REQ-004 — Design Starter Template

`rac schema design --template` shall emit a structurally valid Design starter template.

Example:

```markdown
# Design Title

## Context

TODO: describe the design context and why this design exists.

<!-- What situation, product area, or user experience does this design address? -->
<!-- Why is this design needed now? -->

## User Need

TODO: describe who this design is for and what they need to accomplish.

<!-- Who is the user or audience? -->
<!-- What task, pain point, or goal does this design support? -->

## Design

TODO: describe the proposed experience, interaction, layout, flow, or system behavior.

<!-- What is the proposed design? -->
<!-- How should the experience work? -->

## Constraints

TODO: describe technical, product, accessibility, platform, or implementation constraints.

<!-- What constraints shape this design? -->
<!-- What must the design respect or avoid? -->

## Rationale

TODO: explain why this design approach was chosen.

<!-- Why is this the preferred approach? -->
<!-- What trade-offs does this design make? -->

## Alternatives

TODO: describe alternatives that were considered.

<!-- What other approaches were considered? -->
<!-- Why were they not chosen? -->

## Accessibility

TODO: describe accessibility considerations.

<!-- What accessibility needs should this design support? -->
<!-- Are there keyboard, contrast, readability, or screen-reader considerations? -->

## Style Guidance

TODO: describe visual, tone, layout, or interaction style guidance.

<!-- What visual or interaction style should be followed? -->
<!-- What patterns should remain consistent? -->

## Open Questions

TODO: list unresolved design questions.

<!-- What still needs to be decided? -->
<!-- What should be validated or explored further? -->
```

Optional relationship sections shall appear in schema output and JSON but shall not be included in starter templates by default.

---

### REQ-005 — Design Inspection

`rac inspect` shall classify Design artifacts.

Example:

```bash
rac inspect design.md
```

Output:

```text
Artifact Type: Design
Confidence: 0.87
```

Design classification shall remain deterministic and schema-driven.

Invalid but sufficiently complete Design artifacts may still classify as Design when they meet the global classification threshold.

Example:

```markdown
# TUI Navigation Model

## Context

TODO: describe why navigation matters.

## User Need

TODO: describe the user need.

## Design

TODO: describe the proposed navigation model.
```

Expected behavior:

- classify as Design if the global classification threshold is met
- fail validation due to missing Constraints

A Design artifact with too few Design-specific sections may classify as Unknown.

Design classification shall not use AI inference or title-only matching.

Design classification shall not change existing Requirement, Decision, Roadmap, or Prompt classification behavior.

---

### REQ-006 — Design Validation

`rac validate` shall validate Design artifacts against the Design schema.

A valid Design artifact requires:

- one top-level title
- Context
- User Need
- Design
- Constraints

Missing required sections shall fail validation.

Stable error codes shall include:

- `missing-context`
- `missing-user-need`
- `missing-design`
- `missing-constraints`

Recommended and optional sections shall not fail validation.

Recommended and optional sections shall not produce validation warnings.

---

### REQ-007 — Design Statistics

`rac stats` shall include Design artifacts in repository statistics.

Design artifacts shall be counted separately from Requirements, Decisions, Roadmaps, and Prompts.

Human output shall include Design counts when present.

Example:

```text
Artifacts

Requirements: 12
Decisions: 8
Roadmaps: 3
Prompts: 5
Designs: 4
Unknown: 1
```

JSON output shall include Design statistics additively.

Example:

```json
{
  "designs": {
    "count": 4
  }
}
```

Design support shall not modify existing Requirement, Decision, Roadmap, or Prompt totals.

---

### REQ-008 — Design Improvement

`rac improve` shall support Design artifacts through existing schema guidance.

Improvement shall remain generic and schema-driven.

Example:

```bash
rac improve design.md
```

Output:

```text
Artifact Type: Design

Missing Recommended:
- Accessibility
- Style Guidance
- Open Questions
```

Guidance examples:

```text
Missing User Need:
- Who is the user or audience?
- What task, pain point, or goal does this design support?

Missing Constraints:
- What constraints shape this design?
- What must the design respect or avoid?

Missing Accessibility:
- What accessibility needs should this design support?
- Are there keyboard, contrast, readability, or screen-reader considerations?
```

Design support shall not introduce design-specific improvement engines.

Avoid:

```python
if artifact.type == "design":
    improve_design()
```

The pipeline shall remain:

```text
ArtifactSpec
      ↓
generic improve engine
      ↓
artifact output
```

---

### REQ-009 — Design JSON Output

Design support shall be reflected in JSON outputs for:

- `rac schema design --json`
- `rac inspect design.md --json`
- `rac stats . --json`
- `rac improve design.md --json`

JSON output shall remain additive and backwards compatible where possible.

Section names shall use existing normalization:

- lowercase
- snake_case
- derived from Markdown headings

Example:

```text
User Need
```

normalizes to:

```text
user_need
```

---

### REQ-010 — No Design Tooling

RAC shall not become a design tool.

Design artifacts are structured knowledge documents, not executable design systems.

Not:

```bash
rac design render design.md
```

or:

```bash
rac design export figma design.md
```

---

### REQ-011 — No UI Rendering

RAC shall not render visual designs, screens, wireframes, mockups, or component previews.

Design artifacts may describe experience and interaction design, but RAC shall not produce visual UI output.

---

### REQ-012 — No Component System

RAC shall not manage component libraries, design tokens, CSS, themes, assets, or implementation-level UI systems.

Design artifacts may reference these concepts, but RAC Core shall not own or generate them.

---

## Non-Goals

### Pixel-Perfect Design Specs

Not:

```text
This screen should be exactly 1024px wide with 16px padding.
```

RAC shall not become a pixel-level design specification system.

---

### Figma Replacement

Not:

```text
RAC replaces Figma or other design tools.
```

RAC captures design knowledge and rationale, not visual design files.

---

### Component Library Management

Not:

```text
Button.primary uses token color.blue.500.
```

RAC shall not manage component implementation details, CSS, design tokens, or assets.

---

### Visual Rendering

Not:

```bash
rac design preview design.md
```

No visual preview or rendering engine is included.

---

### Design Quality Scoring

Not:

```text
This design is weak.
```

RAC shall not score design quality.

---

### AI Design Review

Not:

```text
Suggest a better interface design.
```

No AI design critique, generation, or review is included.

---

### Work Management

Design artifacts shall not introduce:

- owners
- assignees
- due dates
- delivery dates
- sprints
- priorities
- workflow states
- capacity planning

RAC manages knowledge, not work.

---

### Relationship Analysis

Optional sections such as Related Requirements, Related Decisions, Related Roadmaps, and Related Prompts may be represented structurally.

However, v0.6.3 shall not parse, validate, resolve, or analyze relationships.

Relationship analysis belongs to v0.7.x.

---

## Success Metrics

### Functional

- Design is registered as an `ArtifactSpec`.
- Design files classify correctly.
- Invalid but sufficiently complete Design files receive Design-specific validation errors.
- Existing Requirement, Decision, Roadmap, and Prompt classification behavior remains unchanged.
- `rac validate` supports Design artifacts.
- `rac inspect` supports Design artifacts.
- `rac stats` counts Design artifacts separately.
- `rac schema design --template | rac validate -` passes.
- `rac improve` supports Design artifacts through schema guidance.
- No design-tooling behavior exists.
- No work-management behavior exists.

### Product

Users can store and review design knowledge as structured, version-controlled artifacts.

Users can create a structurally valid Design artifact using:

```bash
rac schema design --template
```

Users can capture design context, user need, proposed design, constraints, rationale, accessibility considerations, style guidance, and open questions without relying on a separate design document format.

RAC Explorer / TUI design documentation can be dogfooded as RAC-native Design artifacts before v0.8.x implementation.

---

## Risks

### Risk: RAC Becomes a Design Tool

Design artifacts could pull RAC toward visual rendering, component libraries, design tokens, asset management, or Figma replacement.

Mitigation:

Keep Design artifacts focused on knowledge:

- context
- user need
- design rationale
- constraints
- accessibility
- style guidance
- open questions

Do not introduce design rendering, asset management, or component-library behavior.

---

### Risk: Design Artifacts Overlap With Requirements

Some design documents may describe required behavior.

Mitigation:

Use the following boundary:

- Requirement: what must be true
- Decision: what choice was made
- Roadmap: where the product is heading
- Prompt: how humans instruct AI
- Design: how an experience, interaction, or system should work

If a document primarily lists mandatory behavior, it should be a Requirement.

If it primarily describes experience shape, interaction model, constraints, and rationale, it should be a Design artifact.

---

### Risk: Design Artifacts Become Work Management

Design docs may be tempted to include ownership, delivery timing, status, or task coordination.

Mitigation:

Follow ADR-017.

Design artifacts must not introduce:

- owners
- due dates
- sprints
- priorities
- workflow states

---

### Risk: Artifact-Specific Logic Grows

Design support could introduce design-only validators, renderers, or improvement engines.

Mitigation:

Design must use the same architecture as Requirements, Decisions, Roadmaps, and Prompts.

Any new behavior should improve the artifact system, not create Design-only paths.

---

## Assumptions

Design artifacts are source knowledge artifacts.

A Design artifact describes:

- context
- user need
- proposed design
- constraints
- rationale
- alternatives
- accessibility
- style guidance
- open questions

A Design artifact does not store:

- visual assets
- screenshots
- Figma files
- CSS tokens
- implementation components
- project tasks
- delivery status

Design artifacts may later participate in relationships such as:

- Design implements Requirement
- Design follows Decision
- Design supports Roadmap
- Design informs Prompt

but v0.6.3 does not implement relationship parsing.

---

## Acceptance Criteria

```bash
rac schema --list
```

includes:

```text
design
```

```bash
rac schema design
```

displays the Design schema.

```bash
rac schema design --json
```

returns the Design schema as structured JSON.

```bash
rac schema design --template
```

emits a structurally valid Design starter template.

```bash
rac schema design --template | rac validate -
```

passes.

```bash
rac inspect design.md
```

classifies the file as a Design artifact.

```bash
rac validate design.md
```

validates required Design sections.

```bash
rac improve design.md
```

reports missing required and recommended Design sections with guidance.

```bash
rac stats .
```

counts Design artifacts separately from Requirements, Decisions, Roadmaps, and Prompts.

Design support does not introduce rendering, design tooling, or component-library behavior.

Design support does not introduce work-management fields.

No files are modified.

Existing Requirement, Decision, Roadmap, and Prompt behavior remains unchanged.

---

## Future Considerations

Future releases may introduce:

- Design relationship analysis
- Design-to-requirement links
- Design-to-decision links
- Design-to-roadmap links
- Design-to-prompt links
- Design pattern libraries outside RAC Core
- Viewer integrations for Design artifacts
- RAC Explorer views that consume Design artifacts

These capabilities should build on Design artifacts without turning RAC Core into a visual design tool, component system, or project-management platform.