zoriya/v10
1
0
Fork 0
mirror of https://github.com/zoriya/v10.git synced 2026-08-16 02:45:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(root): separate design from rfcs (#351)

Browse Source
This commit is contained in:
rahim
2026-01-28 23:25:57 +11:00
committed by GitHub
parent 432b662440
commit 24d8f14443
21 changed files with 430 additions and 241 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/plans/README.md
+4 -12
View File
@@ -53,16 +53,8 @@ Brief description of what was implemented.
Any gotchas or important context for future reference.
```
## Relationship to RFCs
## See Also
Plans may link to their parent RFC:
```markdown
# Implementing Feature X
**RFC:** [/rfc/feature-x.md](/rfc/feature-x.md)
## Tasks
...
```
- [Design Docs](/internal/design/README.md) — Decisions you own
- [RFCs](/rfc/README.md) — Proposals needing buy-in
- [CLAUDE.md](/CLAUDE.md#design-documents) — How these relate
.claude/skills/README.md
+3 -2
View File
@@ -10,7 +10,7 @@ Specialized knowledge for AI agents working on Video.js 10.
| Building Lit components | `component` + `aria` |
| Building React components | `component` + `aria` |
| Writing documentation | `docs` |
| Writing RFCs | `rfc` |
| Writing Design Docs / RFCs | `design` or `rfc` |
| Reviewing API/architecture | `api` → `review/workflow.md` |
| Reviewing documentation | `docs` → `review/workflow.md` |
| Reviewing components | `component` → `review/workflow.md` |
@@ -32,11 +32,12 @@ Specialized knowledge for AI agents working on Video.js 10.
| [commit-pr](commit-pr/SKILL.md) | Commit changes and create/update PRs with conventions | No |
| [component](component/SKILL.md) | Build headless UI components — compound patterns, state, styling | Yes |
| [create-skill](create-skill/SKILL.md) | Create new skills with proper structure and conventions | No |
| [design](design/SKILL.md) | Write Design Docs — decisions you own, component specs, feature designs| No |
| [docs](docs/SKILL.md) | Write Video.js 10 documentation | Yes |
| [gh-issue](gh-issue/SKILL.md) | Analyze GitHub issues and create implementation plans | No |
| [git](git/SKILL.md) | Git workflow — commit messages, PRs, branch naming, scope inference | No |
| [review-branch](review-branch/SKILL.md) | Review branch changes and suggest improvements | No |
| [rfc](rfc/SKILL.md) | Write RFCs — design docs, architecture proposals, component specs | No |
| [rfc](rfc/SKILL.md) | Write RFCs — proposals needing buy-in (public API, product, DX) | No |
## Review Workflows
.claude/skills/design/SKILL.md
+205
View File
@@ -0,0 +1,205 @@
---
name: design
description: >-
Write Design Docs for Video.js 10. Use for architectural decisions, component specs,
feature designs, and internal patterns you own. Triggers: "write design doc", "create design",
"component spec", "feature design", "document decision".
---
# Design
Write Design Docs for Video.js 10.
Design Docs are for **decisions you own** — architectural choices, component specs, and internal patterns. For proposals needing buy-in from others, use an RFC instead (`rfc/`).
## Reference Material
| Task | Load |
| --------------------- | --------------------------------- |
| Any design task | This file (SKILL.md) |
| Choosing structure | `references/structure.md` |
| Feature guidance | `references/features.md` |
| Component guidance | `references/components.md` |
| Simple decision | `templates/decision.md` |
| Feature (single-file) | `templates/feature-single.md` |
| Feature (multi-file) | `templates/feature-multi.md` |
| Component (basic) | `templates/component-basic.md` |
| Component (compound) | `templates/component-compound.md` |
## When to Write a Design Doc
**Write a Design Doc when:**
- Architectural decisions in your area
- Internal implementation choices
- Design patterns or component specs you own
- Documenting decisions for posterity
**Use an RFC instead when:**
- Changes public API surface
- Affects product direction
- Affects user-facing developer experience
- Significant changes to core architecture
- Needs buy-in from others
**Skip both for:**
- Bug fixes
- Small features in one package
- Implementation details
- Documentation updates
See `internal/design/README.md` for format and file naming.
## Principles
### 1. Start with the Problem
Every design begins with the pain we're solving. A first-time reader needs context before solutions make sense.
```markdown
## Problem
Two concerns, one player:
1. **Media** — play, pause, volume. Owned by `<video>`.
2. **Container** — fullscreen, keyboard. Owned by the UI wrapper.
Different targets, different lifecycles. But users want one API.
```
### 2. Human-Readable
Design Docs are for humans, not machines. Write for someone joining the project tomorrow.
- Explain "why" before "what"
- Define terms on first use
- Link to existing code instead of duplicating
### 3. Concise with Good Flow
Every sentence earns its place. Cut ruthlessly.
```markdown
// ❌ Verbose
In order to ensure that the user is able to interact with the player
in a consistent manner across different platforms, we need to...
// ✅ Direct
Users expect one API. We expose two stores internally, one API externally.
```
### 4. Progressive Disclosure
Start high-level, reveal complexity gradually:
1. **Problem** — What pain exists?
2. **Solution overview** — How do we solve it?
3. **Quick start** — Show it working
4. **Details** — API surface, architecture
5. **Rationale** — Why these choices?
### 5. Code Illustrates Ideas
Code examples show concepts, not implementation details:
```markdown
// ✅ Illustrates the concept
const player = usePlayer();
player.paused; // state
player.play(); // request
// ❌ Implementation detail
function usePlayer() {
const store = useContext(PlayerContext);
const [, forceUpdate] = useReducer(x => x + 1, 0);
// ... 50 more lines
}
```
### 6. Unpack Chronologically
Introduce concepts in the order a reader needs them. Don't reference something before explaining it.
```markdown
// ❌ References unexplained concept
PlayerTarget includes a reference to the media proxy.
// ✅ Explains first, then uses
Media features observe `<video>`. Player features need access to media state.
PlayerTarget includes a media proxy for this coordination.
```
### 7. Examine Existing Code
Before writing, explore relevant parts of the codebase. Link to existing patterns rather than duplicating.
```markdown
Based on the existing `SnapshotController` pattern. See `packages/store/src/snapshot.ts`.
```
### 8. Track Key Decisions
Record every significant design decision. Include alternatives considered. When a decision evolves, **update the existing entry** — don't append a new one.
```markdown
// ❌ Appending creates confusion
### Flat API Shape (v1)
State and requests on same object.
### Flat API Shape (v2)
Actually, we added namespaces...
// ✅ Update in place, include alternatives
### Flat API Shape
**Decision:** State and requests on same object, no namespaces.
**Alternatives:**
- `.state`/`.request` namespaces — explicit but verbose
- Separate hooks (`usePlayerState`, `usePlayerActions`) — familiar but splits concerns
**Rationale:** Less nesting, proxy tracks at property level. Runtime duplicate detection catches collisions.
```
## Checklist
Before finalizing a Design Doc:
- [ ] Problem before solution — context first
- [ ] Concepts explained before referenced
- [ ] Code illustrates ideas, not implementation
- [ ] Minimal examples — only show what's different, `{/* ... */}` for the rest
- [ ] Scannable — lists and whitespace, not walls of text
- [ ] Single source of truth — explain once, link elsewhere
- [ ] Decisions have alternatives and rationale
- [ ] Decisions updated in place, not appended
- [ ] Examples match current design
- [ ] Focused scope — future work in Open Questions
- [ ] Multi-file if 3+ distinct concepts
- [ ] Frontmatter has correct `status`
## Process
1. **Explore** — Read relevant code, understand current patterns
2. **Choose type** — Decision, feature design, or component spec?
3. **Choose structure** — Single or multi-file?
4. **Draft** — Start with problem, build progressively
5. **Cut** — Remove anything that doesn't earn its place
6. **Link** — Reference existing code, related docs
7. **Review** — Check against checklist
## Related
| Need | Use |
| -------------------------- | ----------------- |
| Proposals needing buy-in | `rfc` skill |
| API design principles | `api` skill |
| Building UI components | `component` skill |
| Writing documentation | `docs` skill |
.claude/skills/rfc/references/components.md → .claude/skills/design/references/components.md
+2 -2
View File
@@ -1,6 +1,6 @@
# Component RFC Guidance
# Component Spec Guidance
General guidance for writing component RFCs.
General guidance for writing component specification Design Docs.
## When to Use
.claude/skills/rfc/references/features.md → .claude/skills/design/references/features.md
+8 -8
View File
@@ -1,20 +1,20 @@
# Feature RFC Guidance
# Feature Design Guidance
General guidance for writing feature RFCs.
General guidance for writing feature Design Docs.
## When to Use
- New public APIs
- Architectural changes affecting multiple packages
- Cross-cutting patterns
- New internal APIs
- Architectural decisions in your area
- Design patterns you're introducing
- Extensibility mechanisms
## Templates
| Template | Use For |
| ----------------------------- | ------------------------------------------- |
| `templates/feature-single.md` | Straightforward proposals with one concept |
| `templates/feature-multi.md` | Complex proposals with 3+ distinct concepts |
| `templates/feature-single.md` | Straightforward designs with one concept |
| `templates/feature-multi.md` | Complex designs with 3+ distinct concepts |
## Structure
@@ -37,7 +37,7 @@ General guidance for writing feature RFCs.
## Reference
See `rfc/player-api/` for a complete multi-file example.
See existing Design Docs in `internal/design/` for examples.
## Related Skills
.claude/skills/rfc/references/structure.md → .claude/skills/design/references/structure.md
+9 -9
View File
@@ -1,6 +1,6 @@
# RFC Structure
# Design Doc Structure
When to use single-file vs multi-file RFCs.
When to use single-file vs multi-file Design Docs.
## Decision Tree
@@ -16,13 +16,13 @@ Is this a single concept with straightforward trade-offs?
**Use when:**
- One concept, one proposal
- One concept, one decision
- Trade-offs fit in one page
- Reader can absorb in one sitting
**Structure:** See [`templates/feature-single.md`](../templates/feature-single.md) for the full template.
**Example:** A new utility function, a small API addition.
**Example:** A new utility function, a small API addition, an internal pattern.
## Multi-File
@@ -35,7 +35,7 @@ Is this a single concept with straightforward trade-offs?
**Structure:**
```
rfc/feature-name/
internal/design/feature-name/
├── index.md # Overview, problem, solution, quick start
├── architecture.md # How it works internally
├── decisions.md # Design decisions and rationale
@@ -52,9 +52,9 @@ rfc/feature-name/
## index.md Contents
The entry point for multi-file RFCs:
The entry point for multi-file Design Docs:
1. **Frontmatter** — Status, links to implementation
1. **Frontmatter** — Status, date
2. **Contents table** — Links to all files with one-line descriptions
3. **Problem** — What pain exists
4. **Solution overview** — High-level approach
@@ -91,11 +91,11 @@ Keep `index.md` focused on "what" — save "why" for `decisions.md` and "how" fo
| `migration.md` | Breaking changes, upgrade path |
| `alternatives.md` | Rejected approaches (rare) |
Use lowercase with hyphens. Match existing patterns in `rfc/`.
Use lowercase with hyphens. Match existing patterns in `internal/design/`.
## Cross-Linking
In multi-file RFCs, link between files:
In multi-file Design Docs, link between files:
```markdown
See [architecture.md](architecture.md) for internal details.
.claude/skills/rfc/templates/component-basic.md → .claude/skills/design/templates/component-basic.md
View File
.claude/skills/rfc/templates/component-compound.md → .claude/skills/design/templates/component-compound.md
View File
.claude/skills/design/templates/decision.md
+23
View File
@@ -0,0 +1,23 @@
---
status: decided
date: YYYY-MM-DD
---
# Title
## Decision
What you decided. Be direct.
## Context
Why this came up. What problem triggered the decision.
## Alternatives Considered
- **Option A** — Why not chosen
- **Option B** — Why not chosen
## Rationale
Why this choice wins. Keep concise.
.claude/skills/rfc/templates/feature-multi.md → .claude/skills/design/templates/feature-multi.md
View File
.claude/skills/rfc/templates/feature-single.md → .claude/skills/design/templates/feature-single.md
View File
.claude/skills/git/references/branch.md
+7 -5
View File
@@ -24,6 +24,7 @@ type/short-description
| `docs/readme-examples` | Update README examples |
| `test/slider-keyboard` | Add keyboard tests for slider |
| `rfc/request-api` | RFC for new request API design |
| `design/queue-design` | Design doc for queue architecture|
| `plan/store-simplification` | Planning store architecture |
## Guidelines
@@ -35,11 +36,12 @@ type/short-description
## Special Branches
| Branch | Purpose |
| -------- | -------------------------------- |
| `main` | Primary branch |
| `rfc/*` | Request for comments / proposals |
| `plan/*` | Planning and discovery work |
| Branch | Purpose |
| ---------- | ---------------------------------- |
| `main` | Primary branch |
| `rfc/*` | Request for comments / proposals |
| `design/*` | Design docs (decisions you own) |
| `plan/*` | Planning and discovery work |
## Issue-Linked Branches
.claude/skills/git/references/scope.md
+2 -1
View File
@@ -15,6 +15,7 @@ Infer commit scope from changed file paths.
| `packages/icons/` | `icons` |
| `site/` | `site` |
| `rfc/` | `rfc` |
| `internal/design/` | `design` |
| `.claude/` | `claude` |
| `.github/workflows/` | `ci` |
| `.github/` | `cd` |
@@ -33,7 +34,7 @@ When changes span multiple packages:
From `commitlint.config.js`:
```
cd, ci, claude, core, docs, html, icons, packages,
cd, ci, claude, core, design, docs, html, icons, packages,
plan, react-native, react, rfc, root, site, store,
test, utils
```
.claude/skills/rfc/SKILL.md
+46 -158
View File
@@ -1,38 +1,41 @@
---
name: rfc
description: >-
Write and review RFCs for Video.js 10. Use for design documents, architecture decisions,
API proposals, and UI component specifications. Triggers: "write RFC", "create RFC",
"design doc", "review rfc", "component spec", "architecture proposal".
Write RFCs for Video.js 10. Use for proposals that need buy-in — public API changes,
product direction, user-facing DX, core architecture. Triggers: "write RFC", "create RFC",
"propose", "need buy-in", "architecture proposal".
---
# RFC
Write Request for Comments (RFC) documents for Video.js 10.
RFCs are for **proposals that need buy-in** from others before proceeding. For decisions you own, use a Design Doc instead (`design` skill, `internal/design/`).
## Reference Material
| Task | Load |
| --------------------- | --------------------------------- |
| Any RFC task | This file (SKILL.md) |
| Choosing structure | `references/structure.md` |
| Feature guidance | `references/features.md` |
| Component guidance | `references/components.md` |
| Feature (single-file) | `templates/feature-single.md` |
| Feature (multi-file) | `templates/feature-multi.md` |
| Component (basic) | `templates/component-basic.md` |
| Component (compound) | `templates/component-compound.md` |
| Task | Load |
| ------------------ | ----------------------------------- |
| Any RFC task | This file (SKILL.md) |
| Writing principles | `design` skill (Principles section) |
## When to Write an RFC
**Write an RFC for:**
**Write an RFC when:**
- Major API changes or new APIs
- Architectural decisions affecting multiple packages
- Design patterns used across the codebase
- UI component specifications
- Changes public API surface
- Affects product direction
- Affects user-facing developer experience
- Significant changes to core architecture
- Needs buy-in from others
**Skip the RFC for:**
**Use a Design Doc instead when:**
- Architectural decisions in your area
- Internal implementation choices
- Design patterns or component specs you own
**Skip both for:**
- Bug fixes
- Small features in one package
@@ -41,153 +44,38 @@ Write Request for Comments (RFC) documents for Video.js 10.
See `rfc/README.md` for status lifecycle, branch workflow, and relationship to implementation plans.
## Principles
### 1. Start with the Problem
Every RFC begins with the pain we're solving. A first-time reader needs context before solutions make sense.
```markdown
## Problem
Two concerns, one player:
1. **Media** — play, pause, volume. Owned by `<video>`.
2. **Container** — fullscreen, keyboard. Owned by the UI wrapper.
Different targets, different lifecycles. But users want one API.
```
### 2. Human-Readable
RFCs are for humans, not machines. Write for someone joining the project tomorrow.
- Explain "why" before "what"
- Define terms on first use
- Link to existing code instead of duplicating
### 3. Concise with Good Flow
Every sentence earns its place. Cut ruthlessly.
```markdown
// ❌ Verbose
In order to ensure that the user is able to interact with the player
in a consistent manner across different platforms, we need to...
// ✅ Direct
Users expect one API. We expose two stores internally, one API externally.
```
### 4. Progressive Disclosure
Start high-level, reveal complexity gradually:
1. **Problem** — What pain exists?
2. **Solution overview** — How do we solve it?
3. **Quick start** — Show it working
4. **Details** — API surface, architecture
5. **Rationale** — Why these choices?
### 5. Code Illustrates Ideas
Code examples show concepts, not implementation details:
```markdown
// ✅ Illustrates the concept
const player = usePlayer();
player.paused; // state
player.play(); // request
// ❌ Implementation detail
function usePlayer() {
const store = useContext(PlayerContext);
const [, forceUpdate] = useReducer(x => x + 1, 0);
// ... 50 more lines
}
```
### 6. Unpack Chronologically
Introduce concepts in the order a reader needs them. Don't reference something before explaining it.
```markdown
// ❌ References unexplained concept
PlayerTarget includes a reference to the media proxy.
// ✅ Explains first, then uses
Media features observe `<video>`. Player features need access to media state.
PlayerTarget includes a media proxy for this coordination.
```
### 7. Examine Existing Code
Before writing, explore relevant parts of the codebase. Link to existing patterns rather than duplicating.
```markdown
Based on the existing `SnapshotController` pattern. See `packages/store/src/snapshot.ts`.
```
### 8. Track Key Decisions
Record every significant design decision in `decisions.md`. Include alternatives considered. When a decision evolves, **update the existing entry** — don't append a new one.
```markdown
// ❌ Appending creates confusion
### Flat API Shape (v1)
State and requests on same object.
### Flat API Shape (v2)
Actually, we added namespaces...
// ✅ Update in place, include alternatives
### Flat API Shape
**Decision:** State and requests on same object, no namespaces.
**Alternatives:**
- `.state`/`.request` namespaces — explicit but verbose
- Separate hooks (`usePlayerState`, `usePlayerActions`) — familiar but splits concerns
**Rationale:** Less nesting, proxy tracks at property level. Runtime duplicate detection catches collisions.
```
## Checklist
Before finalizing an RFC:
- [ ] Problem before solution — context first
- [ ] Concepts explained before referenced
- [ ] Code illustrates ideas, not implementation
- [ ] Minimal examples — only show what's different, `{/* ... */}` for the rest
- [ ] Scannable — lists and whitespace, not walls of text
- [ ] Single source of truth — explain once, link elsewhere
- [ ] Decisions have alternatives and rationale
- [ ] Decisions updated in place, not appended
- [ ] Examples match current proposal
- [ ] Focused scope — future work in Open Questions
- [ ] Multi-file if 3+ distinct concepts
- [ ] Problem clearly stated — why is this worth solving now?
- [ ] Solution is high-level — details come in Design Docs after approval
- [ ] Alternatives considered with pros/cons
- [ ] Trade-offs are explicit
- [ ] Open questions listed
- [ ] Next steps clear (what happens if approved)
- [ ] Frontmatter has `status: draft`
## Process
1. **Explore** — Read relevant code, understand current patterns
2. **Choose type** — Feature RFC or Component RFC?
3. **Choose structure** — Single or multi-file?
4. **Draft** — Start with problem, build progressively
5. **Cut** — Remove anything that doesn't earn its place
6. **Link** — Reference existing code, related RFCs
7. **Review** — Check against checklist
1. **Identify need** — Does this actually need buy-in? If not, write a Design Doc
2. **Draft proposal** — Focus on problem and approach, not implementation details
3. **List alternatives** — Show you've considered other options
4. **Surface trade-offs** — Be honest about costs
5. **Gather feedback** — Share with affected parties
6. **Iterate** — Update based on feedback
7. **Get approval** — Move to `status: accepted` when agreed
8. **Document** — Write Design Doc with full details after approval
## Writing Principles
For detailed writing guidance (progressive disclosure, conciseness, etc.), see the `design` skill's Principles section. The same principles apply to RFCs.
## Related
| Need | Use |
| ---------------------- | ----------------- |
| API design principles | `api` skill |
| Building UI components | `component` skill |
| Writing documentation | `docs` skill |
| Need | Use |
| -------------------------- | ----------------- |
| Decisions you own | `design` skill |
| API design principles | `api` skill |
| Building UI components | `component` skill |
| Writing documentation | `docs` skill |
CLAUDE.md
+16 -7
View File
@@ -468,16 +468,25 @@ add(cleanup: CleanupFn): void { ... }
## Design Documents
| Location | Purpose |
| ---------------- | ----------------------------------------------------------------- |
| `rfc/` | Design proposals, API decisions, architecture — public discussion |
| `.claude/plans/` | Implementation notes, AI-agent context, working drafts |
| Location | Purpose |
| ------------------ | ---------------------------------------------------------- |
| `internal/design/` | Decisions you own — document for posterity |
| `rfc/` | Proposals needing buy-in — get alignment before committing |
| `.claude/plans/` | Implementation notes, AI-agent context, working drafts |
**RFCs** focus on **what** and **why**. Write an RFC for major API changes, architectural decisions, or patterns used across packages.
### Design Doc vs RFC
**Implementation plans** focus on **how**. Use `.claude/plans/` for step-by-step implementation details, debugging notes, and AI-agent context.
| | Design Doc | RFC |
| -------------- | ---------------------- | -------------------------------- |
| **Scope** | Your area of work | Shared concerns or public API |
| **Approval** | None needed | Needs buy-in from others |
| **Purpose** | Document for posterity | Get alignment first |
Before merging, compact completed plans: keep key decisions and important notes, point to PRs/commits for details. See `.claude/plans/README.md`.
**Design Docs** — Decisions you own. Write one when making significant decisions in your area, choosing between approaches, or documenting architecture others will build on. See `internal/design/README.md`.
**RFCs** — Cross-team alignment. Write one when the decision affects multiple areas, changes shared API surface, or is hard to reverse. See `rfc/README.md`.
**Implementation plans** — Step-by-step details for **how** to implement. Use `.claude/plans/` for implementation notes, debugging discoveries, and AI-agent context. Compact before merging.
## Rule Placement
CONTRIBUTING.md
+7 -7
View File
@@ -172,17 +172,17 @@ When your changes introduce new patterns:
- **Code conventions** → Update `CLAUDE.md` Code Rules section
- **Domain patterns** → Update relevant skill in `.claude/skills/`
## RFCs (Design Documents)
## Design Docs and RFCs
For significant architectural decisions and API designs, we use RFCs (Request for Comments). See [`rfc/README.md`](./rfc/README.md) for the full process.
We use two types of design documents:
**When to write an RFC:**
**Design Docs** (`internal/design/`) — Decisions you own, documented for posterity. Write one when making significant decisions in your area, choosing between approaches, or documenting architecture. See [`internal/design/README.md`](./internal/design/README.md).
- Introducing a new public API surface
- Making architectural changes affecting multiple packages
- Proposing patterns used throughout the codebase
**RFCs** (`rfc/`) — Proposals needing buy-in from others. Write one when the decision affects multiple areas, changes shared API surface, or is hard to reverse. See [`rfc/README.md`](./rfc/README.md).
**Skip the RFC for:** Bug fixes, small contained features, implementation details.
**Rule of thumb:** If you need someone else's approval, it's an RFC. If you're documenting your own decision, it's a Design Doc.
**Skip both for:** Bug fixes, small contained features, implementation details.
## Creating a Pull Request
commitlint.config.js
+1
View File
@@ -17,6 +17,7 @@ export default {
'ci',
'claude',
'core',
'design',
'docs',
'html',
'icons',
internal/design/README.md
+76
View File
@@ -0,0 +1,76 @@
# Design Docs
Decisions you own — documented for posterity.
## What Belongs Here
Design Docs are **decisions you own**. Write one when:
- Making architectural decisions in your area
- Choosing between implementation approaches
- Introducing design patterns others will follow
- Documenting internal APIs or component specs
## When to Use RFC Instead
Use an RFC (`rfc/`) when:
- Changes public API surface
- Affects product direction
- Affects user-facing developer experience
- Significant changes to core architecture
- Hard to reverse once shipped
**Rule of thumb:** If you need someone else's approval, it's an RFC. If you're documenting your own decision, it's a Design Doc.
## Format
```markdown
---
status: decided
date: 2025-01-27
---
# Title
## Decision
What you decided. Be direct.
## Context
Why this came up. What problem triggered the decision.
## Alternatives Considered
- **Option A** — Why not chosen
- **Option B** — Why not chosen
## Rationale
Why this choice wins. Keep concise.
```
## Status Values
| Status | Meaning |
|--------|---------|
| `draft` | Thinking through it, not final |
| `decided` | Decision made, documented |
| `superseded` | Replaced by another design doc |
## File Naming
Use lowercase with hyphens:
```
queue-design.md
hook-naming.md
skin-theming.md
```
## See Also
- [RFCs](/rfc/README.md) — Proposals needing buy-in
- [Plans](/.claude/plans/README.md) — Implementation details
- [CLAUDE.md](/CLAUDE.md#design-documents) — How these relate
rfc/feature-availability-design.md → internal/design/feature-availability-design.md
+2 -1
View File
@@ -1,5 +1,6 @@
---
status: draft
date: 2025-01-27
---
# Feature Availability Design
@@ -37,7 +38,7 @@ type FeatureAvailability = 'available' | 'unavailable' | 'unsupported';
## Related: Missing Feature vs Unavailable Capability
See [player-api](./player-api/index.md) for feature access patterns.
See [player-api](/rfc/player-api/index.md) for feature access patterns.
| Concept | Cause | Detection |
| ---------------------- | ------------------- | --------------------------------- |
rfc/store/queue-design.md → internal/design/queue-design.md
+2 -1
View File
@@ -1,5 +1,6 @@
---
status: implemented
status: decided
date: 2025-01-27
---
# Store Queue Design
rfc/README.md
+17 -28
View File
@@ -1,31 +1,29 @@
# RFCs
Request for Comments (RFC) documents for Video.js 10 architecture and API design decisions.
Proposals that need buy-in before proceeding.
## What Belongs Here
RFCs document significant design decisions that benefit from review and discussion:
RFCs are for proposals that require alignment from others:
- Major API changes or new APIs
- Architectural decisions
- Design patterns used across packages
- Breaking changes with migration paths
- Changes to public API surface
- Product direction decisions
- User-facing developer experience changes
- Significant changes to core architecture
## When to Write an RFC
Write an RFC when:
- Introducing a new public API surface
- Making architectural changes that affect multiple packages
- Proposing patterns that will be used throughout the codebase
- Changes need input from multiple contributors
- Changes public API surface
- Affects product direction
- Affects user-facing developer experience
- Significant changes to core architecture
- Needs buy-in from others
Skip the RFC for:
**Use a Design Doc instead** (`internal/design/`) for decisions you own — architectural choices in your area, internal patterns, component specs.
- Bug fixes
- Small features contained to one package
- Implementation details that don't affect public APIs
- Documentation updates
**Skip both for:** Bug fixes, small features, implementation details, documentation updates.
## File Format
@@ -95,17 +93,8 @@ When the RFC is accepted and merged, the squash commit becomes:
docs(rfc): player api
```
## Relationship to Implementation Plans
## See Also
RFCs focus on **what** and **why** — the design, rationale, and public API.
Implementation details live in `.claude/plans/` — step-by-step plans, code snippets, and AI-agent context for executing the RFC.
An RFC may link to its implementation plan:
```markdown
---
status: implemented
implementation-plan: .claude/plans/feature-name.md
---
```
- [Design Docs](/internal/design/README.md) — Decisions you own
- [Plans](/.claude/plans/README.md) — Implementation details
- [CLAUDE.md](/CLAUDE.md#design-documents) — How these relate