refs
Skill2 starsChanged 3 months agoMITView on GitHub
Parses references from references/ across all 9 design aspects. Finds conflicts (e.g. quiet-luxury mood vs bombastic motion). Produces a coherent proposal for DESIGN-LOCK.md AND an approved-manifest.md that /build and /audit enforce as required elements.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- kaisers-io/refstheir own version, first seen Nov 7, 2026
- jxxsteven7/zotero-librariantheir own version, first seen Oct 11, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- kaisers-io/refs★ 7same name
- jxxsteven7/zotero-librarian★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- animationSkill
- auditSkill
- blocksSkill
- briefSkill
- buildSkill
- copy-analyzeSkill
- deploySkill
- design-lockSkill
- iconsSkill
- inboxSkill
- mediaSkill
- mobileSkill
- tokensSkill
- typographySkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 8 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
After brief/05-design.md is filled.
- Very specific: line 23
If no references at all — offer to base the design on brief/05-design.md and skip this skill.
- Very specific: line 31
Read every subfolder: source.txt, notes.md, media files.
- Distinctive: line 32
If the user provided a URL but no screenshot, WebFetch the visual/structure (do not pull code).
- Distinctive: line 55
Run through the pairs:
- Very specific: line 107
Ask: approved? Anything to change before /design-lock?
- Distinctive: line 156
Conflicts are questions, not decisions: Do not decide for the user.
- Distinctive: line 157
Full-sites count as a single reference weight: If 1 full-site vs 5 aspect refs — aspects win.
- Distinctive: line 162
Do not "copy" the client's own site (copyright issue + worse result — original beats copy).
- Distinctive: line 163
Do not push the fashion of the moment ("everyone does glassmorphism right now") — go from brand and mood.
- Distinctive: line 164
Do not decide without the user — if uncertain, ask.
- Distinctive: line 165
Do not skip Step 5b even if there are no obvious manifest items.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/refs
Reads every folder under references/*/, extracts patterns per aspect, surfaces conflicts, and produces two artifacts:
references/proposal.md— recommendations for/design-lock.references/approved-manifest.md— a flat list of required elements the user approved (see Step 5b).
When to use
- After
brief/05-design.mdis filled. - The user placed references in
references/. - Before
/design-lock.
Requirements
- At least 1 reference exists somewhere under
references/*/. brief/05-design.mdis filled (mood, associations).
If no references at all — offer to base the design on brief/05-design.md and skip this skill.
Process
Step 1. Walk every aspect folder.
For each folder in references/:
animation/,structure/,typography/,color/,layout/,motion/,micro-interactions/,mood/,full-sites/- Read every subfolder:
source.txt,notes.md, media files. - If the user provided a URL but no screenshot, WebFetch the visual/structure (do not pull code).
Step 2. Extract the common pattern per aspect.
For each aspect, articulate what's shared across references:
## animation
From 3 references:
- Common pattern: subtle scale-up on hover (1.02×), fade + slight lift on scroll
- Common ease: cubic-bezier(0.22, 1, 0.36, 1)
- Common duration: ~300ms
- Outlier: <linear-refs uses longer 500ms>
## typography
- Serif heading + sans body (2 of 3)
- Ratio ~1.333 (Perfect Fourth)
- Weights: 400 body, 700 headings — only two
- Heading line-height: 1.1 (tight, editorial)Step 3. Detect conflicts.
Run through the pairs:
- Mood vs Motion: "quiet luxury" + "bombastic scroll animations" → conflict.
- Color vs Mood: "warm beige" + "neon accent" → conflict (unless neon is a declared subversion).
- Density vs Typography: "compact" + "editorial serif big display" → conflict.
- Density vs Structure: "editorial density" + "5+ sections" → conflict (editorial = fewer sections, more air).
Each conflict is a question to the user:
⚠️ Conflict: mood/aesop = "quiet luxury" vs motion/apple-scroll = "bombastic sticky"
Which wins?
- A. Mood wins → pick a more subtle motion (e.g. Vercel scroll fade)
- B. Motion wins → revisit mood, pick something bolder
- C. Compromise: quiet mood + one bombastic hero sceneStep 4. Build the proposal for DESIGN-LOCK.
Assemble a single document — what will be proposed for DESIGN-LOCK.md. Every point (spacing, type, color, radius, motion, density, photography, sections) gets a proposal with a reason:
## Proposal for DESIGN-LOCK
### 1. Spacing
Base: 8px
Rhythm: Fibonacci 8/16/24/40/64
Section padding: 96px top, 96px bottom
Page margin (left/right): 5% viewport (min 24px, max 120px)
Why: editorial density from mood + typical rhythm for serif-driven landings
### 2. Type
Ratio: 1.333 (Perfect Fourth)
Body: 17px, line-height 1.6
H1: 56px desktop / 32px mobile
Weights: 400 + 700 (two)
Font: Editorial New heading + Inter body
Why: all 3 typography refs use this ratio
### 3. Color
Mode: mono + accent
Background: #F5F1EA (warm beige)
Foreground: #1A1A1A (off-black)
Accent: #C69C6D (rare — only on CTA and underline)
Why: from color/aesop-mono-warm, matches quiet-luxury mood
...Step 5. Save the proposal.
- Save
references/proposal.md(temporary, feeds/design-lock). - Show the user a summary.
- Ask: approved? Anything to change before
/design-lock?
Step 5b. Approved manifest — required elements.
After proposal approval, extract every concrete element that the user explicitly approved and add it to references/approved-manifest.md. This file is the contract — /build refuses to save a section that omits a manifest item relevant to it, and /audit fails the whole build if any manifest item is unmet.
Manifest format:
# Approved manifest
Every item here MUST appear in the final build. If an item is impossible for the current layout, it must be explicitly removed from this file by the user — not silently dropped.
## From /refs
### Motifs
[ ] motif: horizontal thin rule between sections ← ref: mood/aesop
[ ] motif: serif accent on numbers ← ref: typography/nyt
### Patterns
[ ] pattern: 2-column asymmetric grid (60/40) ← ref: layout/vercel-blog
[ ] pattern: sticky brand mark top-left ← ref: full-sites/pentagram
### Elements
[ ] element: quote block with vertical rule ← ref: typography/editorial
[ ] element: image caption overlay bottom-right ← ref: mood/aesop
### Color usage
[ ] color: accent only on CTAs and inline underlines ← ref: color/aesop-monoWhat counts as a manifest item:
- Visual motifs the user pointed to explicitly ("this thin line between sections is what I want").
- Structural patterns approved during conflict resolution.
- Approved elements from
/design-lock§7 imagery discussion (added later by/design-lock). - Approved section types from
/design-lock§8 (added later by/design-lock). - Approved animation behaviors from
/animation(added by/animation). - Approved icons from
/icons(added by/icons).
Every item includes the reference source so the audit report can cite provenance when a check fails.
Ask the user to review the manifest one item at a time. Any item they cannot commit to → remove now, not later. Silently dropping approved elements is exactly the failure mode this file exists to prevent.
Save references/approved-manifest.md. This file is appended to by /design-lock, /animation, and /icons — do not overwrite in later passes.
Rules of behavior
- Reference aspects are inspiration, not verdict. The user can reconsider.
- Always cite the source. Not "propose 8px" but "propose 8px because all three typography refs use this scale base".
- Conflicts are questions, not decisions. Do not decide for the user.
- Full-sites count as a single reference weight. If 1 full-site vs 5 aspect refs — aspects win.
- Never drop an approved manifest item silently. It's the whole point of this file.
What NOT to do
- Do not "copy" the client's own site (copyright issue + worse result — original beats copy).
- Do not push the fashion of the moment ("everyone does glassmorphism right now") — go from brand and mood.
- Do not decide without the user — if uncertain, ask.
- Do not skip Step 5b even if there are no obvious manifest items. Create the file with a note saying "no items from /refs; awaiting /design-lock" so subsequent skills know to append.
Next
/design-lock— freezes decisions based on the proposal; appends more items to the approved manifest.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

