PRIMITIVE
OS

01# PRIMITIVE-SKILL.MD
02# Primitive Design Core — Constraint Engine v1.2
03# Apply this file to any AI coding agent to enforce the Primitive standard.
04# Last updated: 2026-04 | Detroit.Paris.
05 
06## ═══════════════════════════════════════
07## RULE 00: BEFORE YOU WRITE A SINGLE LINE
08## ═══════════════════════════════════════
09 
10Before generating any UI component, confirm the following:
11- You have read this file in full.
12- You will NOT apply any rule that contradicts this spec.
13- You will treat deviations as build failures.
14 
15Zero-tolerance policy. No exceptions. No "but this looks nicer".
16 
17## ═══════════════════════════════════════
18## RULE 01: GEOMETRY & LAYOUT
19## ═══════════════════════════════════════
20 
21border-radius: 0px !important
22→ rounded-*, rounded-xl, rounded-full = FORBIDDEN
23→ Override any third-party component that adds radius
24 
25Borders:
26→ All component borders: 1px solid #1c1c1c (zinc-800)
27→ Borders define structure. They are not decorative.
28→ No box-shadows as a substitute for borders.
29 
30Layout system:
31→ CSS Grid is the primary layout primitive.
32→ Bento-box grid structures preferred over freeform flex.
33→ Gutters: 1px (border-as-divider pattern).
34 
35Spacing scale:
36→ Use multiples of 4px. Never arbitrary pixel values.
37→ Padding inside cards: 24px or 32px. Never 10px or 15px.
38 
39## ═══════════════════════════════════════
40## RULE 02: COLOR SYSTEM
41## ═══════════════════════════════════════
42 
43Primary palette (always present):
44  #000000  — page background
45  #ffffff  — primary text
46  #111111  — component background (elevation 1)
47  #1c1c1c  — border / divider (zinc-800)
48  #444444  — muted text, metadata
49  #888888  — secondary text
50 
51Accent system:
52→ One accent per product/brand. Choose deliberately.
53→ Accent applies to: CTAs, index numbers, hover states, icons.
54→ Never apply accent to body text or headings.
55→ Never use more than one accent on a single screen.
56 
57FORBIDDEN:
58→ bg-gradient-to-* on any background
59→ Pastel colours without explicit brand reason
60→ Transparency hacks to simulate depth (use borders instead)
61→ Pure CSS shadows (box-shadow) on containers
62 
63## ═══════════════════════════════════════
64## RULE 03: TYPOGRAPHY
65## ═══════════════════════════════════════
66 
67Primary typeface: Geist Mono
68→ Applied globally via next/font or @import
69→ letter-spacing: -0.05em on all headings
70→ font-weight: 400 (body) | 700 (headings, labels)
71→ Never font-weight: 500 or 600
72 
73BLACKLISTED fonts:
74→ Inter, Roboto, Open Sans, Lato, Nunito, Poppins
75→ Any rounded sans-serif is considered "slop"
76 
77Heading scale:
78→ h1: clamp(52px, 12vw, 180px) | tracking: -0.08em
79→ h2: clamp(28px, 4vw, 64px)  | tracking: -0.05em
80→ h3: 13–16px | font-bold     | tracking: -0.03em
81 
82Label / metadata style:
83→ UPPERCASE, 8–10px, tracking: 0.2–0.35em, color: #444–#555
84→ Used for section indices, tags, status indicators
85 
86Body copy:
87→ 11–13px, leading: 1.6–1.8, color: #888
88 
89## ═══════════════════════════════════════
90## RULE 04: MOTION PHYSICS
91## ═══════════════════════════════════════
92 
93CSS transitions are BANNED for state changes.
94Use Framer Motion for ALL animated UI state.
95 
96Standard spring config:
97  { type: "spring", mass: 0.5, stiffness: 400, damping: 30 }
98 
99Scroll animations:
100→ useScroll + useTransform for parallax / reveal
101→ whileInView with viewport: { once: true, margin: "-60px" }
102→ Never use CSS @keyframes for UI state
103 
104Page transitions:
105→ AnimatePresence wraps all route-level components
106→ Exit animations always defined (no "disappear instantly")
107 
108Hover interactions:
109→ motion.div with animate prop (not CSS hover: classes)
110→ Spring transitions on x, y, scale, opacity, color
111 
112## ═══════════════════════════════════════
113## RULE 05: WEBGL & GENERATIVE VISUALS
114## ═══════════════════════════════════════
115 
116NO stock images. Period.
117→ Unsplash, Pexels, Getty = BANNED
118→ If you need an image, generate it or use SVG
119 
120React Three Fiber is the WebGL standard:
121→ @react-three/fiber + @react-three/drei
122→ All 3D scenes use Canvas with alpha: true background
123→ Performance: dpr={[1, 1.5]}, powerPreference: "high-performance"
124 
125Generative visuals preferred:
126→ Noise shaders (simplex, Perlin FBM)
127→ Particle systems reacting to mouse/scroll
128→ Procedural geometry (PlaneGeometry with vertex displacement)
129 
130Post-processing (if used):
131→ @react-three/postprocessing only
132→ Bloom intensity: never > 0.4 (no blinding glare)
133 
134## ═══════════════════════════════════════
135## RULE 06: COMPONENT ARCHITECTURE
136## ═══════════════════════════════════════
137 
138All components: strict TypeScript, no 'any' types.
139File naming: PascalCase for components, camelCase for utils.
140Co-location: component-specific hooks live in the same file.
141 
142State management:
143→ useState for local UI state only
144→ No Redux / Zustand unless explicitly required
145→ Context for theme/global only
146 
147Server vs Client:
148→ Mark 'use client' only when needed (interactivity, hooks)
149→ Prefer server components for static sections
150→ Dynamic import R3F components with { ssr: false }
151 
152## ═══════════════════════════════════════
153## RULE 07: ANTI-SLOP CHECKLIST
154## ═══════════════════════════════════════
155 
156Before committing any component, verify:
157 
158[ ] No rounded corners anywhere (0px radius enforced)
159[ ] No stock photography or placeholder images
160[ ] No Tailwind gradient backgrounds
161[ ] No default browser font showing through
162[ ] No magic pixel values (must be on 4px grid)
163[ ] No CSS transition for state changes (use Framer)
164[ ] No more than 1 accent color on the screen
165[ ] All text meets 4.5:1 contrast ratio minimum
166[ ] Hover states defined on all interactive elements
167[ ] All buttons/links have visible focus states
168 
169If any box is unchecked → the component does not ship.
170 
171## ═══════════════════════════════════════
172## RULE 08: INSTALLATION
173## ═══════════════════════════════════════
174 
175To apply this constraint engine to a new project:
176 
1771. Copy this file to your project root as .claudedesignrules.md
1782. Add to your AI agent prompt:
179   "Read .claudedesignrules.md before writing any UI code.
180    Treat all rules as hard constraints, not suggestions."
1813. For Next.js projects, add to next.config.js:
182   experimental: { scrollRestoration: true }
1834. Install required packages:
184   npm install framer-motion @react-three/fiber @react-three/drei
185   npm install simplex-noise geist
186 
187End of file. Build something that lasts.
188# primitive-design-core | github.com/atakanturg/primitive-design-core