Decision record

A skill for creating structured decision records for design system choices. Covers component decisions, token architecture choices, tooling selections, governance policies, and any other decision worth recording so future contributors do not have to reverse-engineer the reasoning.

Before you begin: verify references

Confirm that every path in this skill's frontmatter references: exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example npx skills install) dropped the repo-root knowledge-notes/ directory. Tell the user to reinstall by a method in 1-INSTALL.md and run verify-install.sh from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

Context

Design systems accumulate decisions faster than they accumulate documentation. The result is a system where the current state is known but the reasoning is not — which means the same debates recur, constraints get ignored because their origin is forgotten, and new team members spend weeks learning by collision what a thirty-minute conversation would have covered.

A decision record does not need to be formal. It needs to be findable and honest. The format below is lightweight enough to write in under twenty minutes and structured enough to be useful when someone reads it twelve months later.

Step 0: Decision trigger checklist

Before writing a record, confirm this decision warrants one. Not every choice needs a formal record — but more decisions warrant records than teams typically capture. Use this checklist: