heimdall-agent 1.0.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +57 -26
- package/README.pt-BR.md +443 -0
- package/agents/cloud-engineer.md +77 -0
- package/agents/code-sentinel.md +71 -34
- package/agents/database-architect.md +31 -25
- package/agents/frontend-designer.md +30 -28
- package/agents/mobile-designer.md +25 -24
- package/agents/modernizer.md +68 -0
- package/agents/orchestrator.md +107 -93
- package/agents/reviewer.md +102 -71
- package/agents/security-auditor.md +27 -27
- package/agents/tester.md +97 -90
- package/commands/grill-me.md +20 -4
- package/commands/orchestrate.md +16 -0
- package/commands/orchestrator.md +16 -0
- package/commands/plan.md +17 -1
- package/config/agents.json +31 -3
- package/config/mcp.json +72 -0
- package/config/models.json +26 -16
- package/config/profiles.json +2 -4
- package/config/skills.json +762 -573
- package/docs/SKILLS.md +393 -275
- package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
- package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
- package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
- package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
- package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
- package/docs/runs/skill-audit/2026-11-12-compare-report.json +1028 -0
- package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
- package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
- package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
- package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
- package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
- package/docs/runs/skill-audit/customization-report.json +380 -0
- package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
- package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
- package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
- package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
- package/docs/runs/skill-audit/inventory.json +308 -0
- package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
- package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
- package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
- package/docs/runs/skill-audit/probe.ps1 +16 -0
- package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
- package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
- package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
- package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
- package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
- package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
- package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
- package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
- package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
- package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
- package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
- package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
- package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
- package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
- package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
- package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
- package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
- package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
- package/docs/runs/skill-audit/update-manifest.md +88 -0
- package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
- package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
- package/docs/runs/skill-audit/upstream-status.json +563 -0
- package/docs/runs/skill-audit/verification-results.json +252 -0
- package/doctrine/AGENTS.md +42 -77
- package/hooks/git/pre-commit +11 -0
- package/hooks/heimdall-hook.cjs +81 -2
- package/hooks/herdr-agent-state.ps1 +55 -0
- package/hooks/hooks.json +0 -11
- package/lib/catalog-sync.cjs +167 -0
- package/lib/hermes-context.cjs +57 -0
- package/lib/model-context.cjs +123 -0
- package/lib/path-discovery.cjs +94 -0
- package/package.json +7 -3
- package/playbooks/01-interactive-grilling-gate.md +23 -6
- package/playbooks/02-fast-code-deep-verification.md +3 -2
- package/playbooks/03-adversarial-code-review.md +15 -7
- package/playbooks/05-canonical-plan-template.md +35 -19
- package/playbooks/06-model-registry-matrix.md +24 -13
- package/playbooks/07-legacy-code-modernization.md +74 -0
- package/playbooks/08-backlog-and-change-request-flow.md +122 -0
- package/setup.mjs +592 -172
- package/skills/antislop/SKILL.md +76 -56
- package/skills/antislop/VERSION +1 -0
- package/skills/antislop-copywriting/SKILL.md +407 -372
- package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
- package/skills/antislop-human/SKILL.md +204 -147
- package/skills/antislop-human/contrast-check.py +168 -165
- package/skills/antislop-human/contrast-mcp.py +6 -3
- package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
- package/skills/antislop-human/references/WCAG.md +127 -0
- package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
- package/skills/antislop-ui/SKILL.md +344 -304
- package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
- package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
- package/skills/brainstorming/SKILL.md +296 -265
- package/skills/brainstorming/builder-check-prompt.md +23 -0
- package/skills/brainstorming/scripts/frame-template.html +213 -213
- package/skills/brainstorming/scripts/server.cjs +723 -723
- package/skills/brandkit/SKILL.md +798 -798
- package/skills/brutalist-skill/SKILL.md +93 -92
- package/skills/caveman/README.md +68 -0
- package/skills/caveman/SKILL.md +73 -38
- package/skills/claude-collaborator/SKILL.md +24 -44
- package/skills/clean-code/SKILL.md +152 -0
- package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
- package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
- package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
- package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
- package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
- package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
- package/skills/cloudflare-security-audit/HUNTING.md +251 -251
- package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
- package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
- package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
- package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
- package/skills/cloudflare-security-audit/SKILL.md +192 -192
- package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
- package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
- package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
- package/skills/cloudflare-security-audit/report-schema.json +461 -461
- package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
- package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
- package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
- package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
- package/skills/codebase-design/DEEPENING.md +37 -0
- package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
- package/skills/codebase-design/SKILL.md +114 -0
- package/skills/codex-collaborator/SKILL.md +24 -45
- package/skills/communication-doctrine/SKILL.md +89 -0
- package/skills/diagnosing-superpowers/SKILL.md +1 -1
- package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
- package/skills/diagnosing-superpowers/templates/issue.md +23 -4
- package/skills/domain-modeling/ADR-FORMAT.md +47 -0
- package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
- package/skills/domain-modeling/SKILL.md +74 -0
- package/skills/executing-plans/SKILL.md +6 -56
- package/skills/executing-plans/scripts/task-done +52 -52
- package/skills/executing-plans/scripts/task-start +28 -28
- package/skills/gemini-collaborator/SKILL.md +24 -56
- package/skills/grill-me/SKILL.md +65 -0
- package/skills/handoff/SKILL.md +64 -0
- package/skills/herdr/SKILL.md +243 -0
- package/skills/image-to-code-skill/SKILL.md +1228 -1228
- package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
- package/skills/imagegen-frontend-web/SKILL.md +987 -987
- package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
- package/skills/improve-codebase-architecture/SKILL.md +71 -0
- package/skills/karpathy-guidelines/SKILL.md +67 -67
- package/skills/mcp-engineering/SKILL.md +74 -0
- package/skills/minimalist-skill/SKILL.md +87 -85
- package/skills/output-skill/SKILL.md +49 -49
- package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
- package/skills/owasp-security/reference/languages.md +378 -372
- package/skills/owasp-security/reference/owasp-report.md +1144 -1140
- package/skills/owasp-security/reference/review-checklist.md +134 -132
- package/skills/ponytail/SKILL.md +36 -52
- package/skills/postgres-best-practices/SKILL.md +30 -52
- package/skills/postgres-best-practices/references/backup-restore.md +372 -0
- package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
- package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
- package/skills/postgres-best-practices/references/hot-standby.md +221 -0
- package/skills/postgres-best-practices/references/indexing.md +318 -0
- package/skills/postgres-best-practices/references/logical-replication.md +610 -0
- package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
- package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
- package/skills/postgres-best-practices/references/query-optimization.md +294 -0
- package/skills/postgres-best-practices/references/query-patterns.md +566 -0
- package/skills/postgres-best-practices/references/schema-design.md +362 -0
- package/skills/postgres-best-practices/references/security-roles.md +489 -0
- package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
- package/skills/progressive-disclosure/SKILL.md +68 -0
- package/skills/pstack-discipline/SKILL.md +40 -0
- package/skills/receiving-code-review/SKILL.md +2 -23
- package/skills/requesting-code-review/SKILL.md +7 -36
- package/skills/soft-skill/SKILL.md +99 -98
- package/skills/stitch-skill/DESIGN.md +121 -121
- package/skills/stitch-skill/SKILL.md +185 -184
- package/skills/strix-security/SKILL.md +54 -53
- package/skills/subagent-driven-development/SKILL.md +35 -264
- package/skills/subagent-driven-development/references/batching.md +11 -0
- package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
- package/skills/subagent-driven-development/references/final-review.md +47 -0
- package/skills/subagent-driven-development/references/fix-loop.md +77 -0
- package/skills/subagent-driven-development/references/handling-reports.md +15 -0
- package/skills/subagent-driven-development/references/preflight.md +26 -0
- package/skills/subagent-driven-development/references/resuming.md +12 -0
- package/skills/subagent-driven-development/scripts/review-package +53 -53
- package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
- package/skills/subagent-driven-development/scripts/task-brief +43 -43
- package/skills/systematic-debugging/SKILL.md +283 -306
- package/skills/taste-skill/SKILL.md +542 -1206
- package/skills/taste-skill/references/app-screens.md +1199 -0
- package/skills/taste-skill/references/colour.md +141 -0
- package/skills/taste-skill/references/copy.md +177 -0
- package/skills/taste-skill/references/critique.md +182 -0
- package/skills/taste-skill/references/imagery.md +791 -0
- package/skills/taste-skill/references/layout.md +292 -0
- package/skills/taste-skill/references/motion.md +980 -0
- package/skills/taste-skill/references/research.md +356 -0
- package/skills/taste-skill/references/scenes.md +174 -0
- package/skills/taste-skill/references/tells.md +115 -0
- package/skills/taste-skill/references/type.md +170 -0
- package/skills/test-driven-development/SKILL.md +330 -337
- package/skills/thermo/SKILL.md +67 -0
- package/skills/threat-modeling/SKILL.md +55 -0
- package/skills/to-spec/SKILL.md +75 -0
- package/skills/to-tickets/SKILL.md +105 -0
- package/skills/trailofbits-audit-context/SKILL.md +72 -72
- package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
- package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
- package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
- package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
- package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
- package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
- package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
- package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
- package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
- package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
- package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
- package/skills/verification-before-completion/SKILL.md +0 -14
- package/skills/wayfinder/SKILL.md +128 -0
- package/skills/writing-plans/SKILL.md +11 -15
- package/skills/writing-skills/SKILL.md +21 -303
- package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
- package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
- package/skills/writing-skills/references/bulletproofing.md +80 -0
- package/skills/writing-skills/references/discovery.md +201 -0
- package/skills/writing-skills/references/flowcharts.md +37 -0
- package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
- package/skills/writing-skills/references/persuasion-principles.md +187 -0
- package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
- package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
- package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
- package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
- package/skills/gpt-tasteskill/SKILL.md +0 -74
- package/skills/taste-skill-v1/SKILL.md +0 -226
- /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
- /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
- /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
- /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
- /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
- /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
- /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
- /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
|
@@ -1,1206 +1,542 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: design-taste-frontend
|
|
3
|
-
description:
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
**
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
**
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
###
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
### 6.E DOM Cost
|
|
544
|
-
* Apply grain / noise filters EXCLUSIVELY to fixed, `pointer-events-none` pseudo-elements (e.g., `fixed inset-0 z-[60] pointer-events-none`). NEVER on scrolling containers - continuous GPU repaints destroy mobile FPS.
|
|
545
|
-
* Be aware of bundle size. Motion is not tiny. Three.js is large. Lazy-load anything that's not above-the-fold.
|
|
546
|
-
|
|
547
|
-
### 6.F Z-Index Restraint
|
|
548
|
-
NEVER spam arbitrary `z-50` or `z-10`. Use z-index strictly for systemic layer contexts (sticky navbars, modals, overlays, grain). Document the z-index scale in a project constants file.
|
|
549
|
-
|
|
550
|
-
---
|
|
551
|
-
|
|
552
|
-
## 7. DIAL DEFINITIONS (Technical Reference)
|
|
553
|
-
|
|
554
|
-
### DESIGN_VARIANCE (Level 1-10)
|
|
555
|
-
* **1-3 (Predictable):** Symmetrical CSS Grid (12-col, equal fr-units), equal paddings, centered alignment.
|
|
556
|
-
* **4-7 (Offset):** `margin-top: -2rem` overlaps, varied image aspect ratios (4:3 next to 16:9), left-aligned headers over center-aligned data.
|
|
557
|
-
* **8-10 (Asymmetric):** Masonry layouts, CSS Grid with fractional units (`grid-template-columns: 2fr 1fr 1fr`), massive empty zones (`padding-left: 20vw`).
|
|
558
|
-
* **MOBILE OVERRIDE:** For levels 4-10, asymmetric layouts above `md:` MUST collapse to strict single-column (`w-full`, `px-4`, `py-8`) on viewports `< 768px`.
|
|
559
|
-
|
|
560
|
-
### MOTION_INTENSITY (Level 1-10)
|
|
561
|
-
* **1-3 (Static):** No automatic animations. CSS `:hover` and `:active` states only. `prefers-reduced-motion` is the default mode anyway.
|
|
562
|
-
* **4-7 (Fluid CSS):** `transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1)`. `animation-delay` cascades for load-ins. Focus on `transform` and `opacity`.
|
|
563
|
-
* **8-10 (Advanced Choreography):** Complex scroll-triggered reveals, parallax, scroll-driven animation (CSS `animation-timeline` or GSAP ScrollTrigger). Use Motion hooks. **NEVER use `window.addEventListener('scroll')`** - it is a hard ban, not a "prefer-not." See Section 5.D for the allowed alternatives.
|
|
564
|
-
|
|
565
|
-
### VISUAL_DENSITY (Level 1-10)
|
|
566
|
-
* **1-3 (Art Gallery):** Lots of white space. Huge section gaps (`py-32` to `py-48`). Expensive, clean.
|
|
567
|
-
* **4-7 (Daily App):** Standard web app spacing (`py-16` to `py-24`).
|
|
568
|
-
* **8-10 (Cockpit):** Tight paddings. No card boxes; 1px lines separate data. Mandatory: `font-mono` for all numbers.
|
|
569
|
-
|
|
570
|
-
---
|
|
571
|
-
|
|
572
|
-
## 8. DARK MODE PROTOCOL
|
|
573
|
-
|
|
574
|
-
Dual-mode by default. Never assume light-only unless the brief is print-emulating editorial.
|
|
575
|
-
|
|
576
|
-
### 8.A Token Strategy (pick one, stick to it)
|
|
577
|
-
* **Tailwind `dark:` variant** (default for utility-first projects): every color utility paired with its dark variant (`bg-white dark:bg-zinc-950`, `text-gray-900 dark:text-gray-100`).
|
|
578
|
-
* **CSS variables** (for shadcn/ui, Radix Themes, or component libraries with theming): define semantic tokens (`--surface`, `--surface-elevated`, `--text-primary`, `--accent`) and swap values under `[data-theme="dark"]` or `@media (prefers-color-scheme: dark)`.
|
|
579
|
-
|
|
580
|
-
### 8.B Do Not Prescribe Specific Colors Here
|
|
581
|
-
The brief and brand decide. This skill enforces only:
|
|
582
|
-
* **Contrast** - WCAG AA minimum for body text, AAA target for hero copy.
|
|
583
|
-
* **Hierarchy parity** - visual hierarchy that works in light must work in dark. If a CTA pops in light, it pops in dark.
|
|
584
|
-
* **Brand fidelity** - primary brand color stays recognisable. Don't desaturate the brand into a dark mode.
|
|
585
|
-
* **No pure `#000000` and no pure `#ffffff`** - use off-black (zinc-950, near-black warm gray) and off-white. Pure values kill depth.
|
|
586
|
-
|
|
587
|
-
### 8.C Default Mode
|
|
588
|
-
Respect `prefers-color-scheme` unless the brand insists. Add a manual toggle if either mode would lose key brand expression.
|
|
589
|
-
|
|
590
|
-
### 8.D Test in Both Modes Before Finishing
|
|
591
|
-
Open the page in both modes during development. Do not ship a page you've only seen in one mode.
|
|
592
|
-
|
|
593
|
-
---
|
|
594
|
-
|
|
595
|
-
## 9. AI TELLS (Forbidden Patterns)
|
|
596
|
-
|
|
597
|
-
Avoid these signatures unless the brief explicitly asks for them.
|
|
598
|
-
|
|
599
|
-
### 9.A Visual & CSS
|
|
600
|
-
* **NO neon / outer glows** by default. Use inner borders or subtle tinted shadows.
|
|
601
|
-
* **NO pure black (`#000000`).** Off-black, zinc-950, or charcoal.
|
|
602
|
-
* **NO oversaturated accents.** Desaturate to blend with neutrals.
|
|
603
|
-
* **NO excessive gradient text** for large headers.
|
|
604
|
-
* **NO custom mouse cursors.** Outdated, accessibility-hostile, perf-hostile.
|
|
605
|
-
|
|
606
|
-
### 9.B Typography
|
|
607
|
-
* **AVOID Inter as default.** See Section 4.1. Override path exists.
|
|
608
|
-
* **NO oversized H1s** that just scream. Control hierarchy with weight + color, not raw scale.
|
|
609
|
-
* **Serif constraints:** Serif for editorial / luxury / publication. Not for dashboards.
|
|
610
|
-
|
|
611
|
-
### 9.C Layout & Spacing
|
|
612
|
-
* **Mathematically perfect** padding and margins. No floating elements with awkward gaps.
|
|
613
|
-
* **NO 3-column equal feature cards.** The generic "three identical cards horizontally" feature row is banned. Use 2-column zig-zag, asymmetric grid, scroll-pinned, or horizontal-scroll alternative.
|
|
614
|
-
|
|
615
|
-
### 9.D Content & Data ("Jane Doe" Effect)
|
|
616
|
-
* **NO generic names.** "John Doe", "Sarah Chan", "Jack Su" → use creative, realistic, locale-appropriate names.
|
|
617
|
-
* **NO generic avatars.** No SVG "egg" or Lucide user icons → use believable photo placeholders or specific styling.
|
|
618
|
-
* **NO fake-perfect numbers.** Avoid `99.99%`, `50%`, `1234567`. Use organic, messy data (`47.2%`, `+1 (312) 847-1928`).
|
|
619
|
-
* **NO startup-slop brand names.** "Acme", "Nexus", "SmartFlow", "Cloudly" → invent contextual, premium names that sound real.
|
|
620
|
-
* **NO filler verbs.** "Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize" → concrete verbs only.
|
|
621
|
-
|
|
622
|
-
### 9.E External Resources & Components
|
|
623
|
-
* **NO hand-rolled SVG icons.** Use Phosphor / HugeIcons / Radix / Tabler. Lucide on explicit request only.
|
|
624
|
-
* **Hand-rolled decorative SVGs strongly discouraged** as default (see Section 4.8).
|
|
625
|
-
* **NO div-based fake screenshots.** Never build a fake product UI out of `<div>` rectangles to simulate a screenshot. Use real images, generated images, or skip the preview.
|
|
626
|
-
* **NO broken Unsplash links.** Use `https://picsum.photos/seed/{descriptive-string}/{w}/{h}`, or generated photo placeholders, or actual assets.
|
|
627
|
-
* **shadcn/ui customization:** Allowed, but NEVER in default state. Customize radii, colors, shadows, typography to the project aesthetic.
|
|
628
|
-
* **Production-Ready Cleanliness:** Code visually clean, memorable, meticulously refined.
|
|
629
|
-
|
|
630
|
-
### 9.F Production-Test Tells (banned outright)
|
|
631
|
-
|
|
632
|
-
These patterns came out of real LLM-generated landing-page tests. They are the signatures the model defaults to when it tries to "look designed." Treat them as hard bans unless the brief explicitly calls for one.
|
|
633
|
-
|
|
634
|
-
**Hero & top-of-page**
|
|
635
|
-
* **NO version labels in the hero.** `V0.6`, `v2.0`, `BETA`, `INVITE-ONLY PREVIEW`, `EARLY ACCESS`, `ALPHA` - banned as default eyebrows. Only acceptable when the brief is explicitly about a product launch / preview status.
|
|
636
|
-
* **NO "Brand · No. 01"-style sub-eyebrows.** "Marrow · No. 01 · The 6-quart" type micro-meta lines. Skip them.
|
|
637
|
-
|
|
638
|
-
**Section numbering & micro-labels**
|
|
639
|
-
* **NO section-number eyebrows.** `00 / INDEX`, `001 · Capabilities`, `002 · Featured commission`, `06 · how it works`, `05 · The honest table` - banned. Eyebrows should name the topic in plain language, not enumerate.
|
|
640
|
-
* **NO `01 / 4`-style pagination on images or bento tiles.** If the user can count, they don't need the label.
|
|
641
|
-
* **NO `Scroll · 001 Capabilities`-style scroll cues.** A simple arrow or "Scroll" is enough; no section-number prefix.
|
|
642
|
-
* **NO "Index of Work, 2018 - 2026"-style range labels** as eyebrows. Just say what the section is.
|
|
643
|
-
|
|
644
|
-
**Separators & dots**
|
|
645
|
-
* **The middle-dot (`·`) is rationed.** Maximum 1 per line in metadata strips. Do NOT use it as the default separator for everything ("foo · bar · baz · qux · quux"). If you need a separator family, prefer line breaks, hairlines, or columns.
|
|
646
|
-
* **NO decorative colored status dots on every list/nav/badge.** A colored dot before "ONE Q4 SLOT OPEN" or before every nav link, or every task row - banned by default. Acceptable only when the dot conveys actual semantic state (a server status, an availability flag) and is used sparingly.
|
|
647
|
-
|
|
648
|
-
**Em-dashes & typography flourishes**
|
|
649
|
-
* **NO em-dash (`—`) as a design element OR anywhere else.** See Section 9.G below for the complete, non-negotiable ban. The em-dash character is forbidden in headlines, eyebrows, pills, body copy, quotes, attribution, captions, button text, and alt text. Use the regular hyphen (`-`).
|
|
650
|
-
* **NO `<br>`-broken-and-italicized headlines** as a default "design move." "for thirty\<br\>*years.*" type splits. Headlines should read naturally first, get clever only when the brief demands it.
|
|
651
|
-
* **NO vertical rotated text** ("INDEX OF WORK, 2018 - 2026" rotated 90°). Agency-portfolio cliché. Use it only when the brief is explicitly agency / Awwwards / experimental AND it serves a real composition purpose.
|
|
652
|
-
* **NO crosshair / hairline grid lines as decoration.** Vertical and horizontal lines drawn just to make the page "feel designed" - banned. Use them only when they organize real content.
|
|
653
|
-
|
|
654
|
-
**Fake product previews**
|
|
655
|
-
* **NO div-based fake product UI in the hero** (fake task list, fake terminal, fake dashboard built from styled divs). It is the #1 LLM-design Tell. Use a real screenshot, a generated image, a real component preview, or none at all.
|
|
656
|
-
* **NO fake version footers** ("v0.6.2-rc.1", "last sync 4s ago · main") inside fake screenshots. Adds nothing, screams AI.
|
|
657
|
-
|
|
658
|
-
**Marketing-copy Tells**
|
|
659
|
-
* **NO "Quietly in use at" / "Quietly trusted by"** social-proof headers. Use natural language: "Trusted by", "Used at", "Customers include", or skip the heading entirely if the logos speak.
|
|
660
|
-
* **NO "From the field" / "Field notes" / "Currently on the bench" / "On our desks" / "Loose plates" style poetic labels** on quote, blog, or sidebar sections. Reads as performative-craftsman. Use plain functional labels ("Testimonials", "Latest writing", "Now working on") or skip the label.
|
|
661
|
-
* **NO "We respect the French ones"-style** mock-humble industry-references in body copy. Cute and AI-y.
|
|
662
|
-
* **NO weather / locale strips** ("LIS 14:23 · 18°C") in headers/footers unless the brief is explicitly about a place / time-zone-distributed studio.
|
|
663
|
-
* **NO micro-meta-sentences under eyebrows.** Sentences like *"Each of these is a feature we ship today, not a roadmap promise. The list will stay short on purpose."* sitting under a section heading are clutter. Eyebrow + Headline + Body is enough.
|
|
664
|
-
* **NO generic step labels.** "Stage 1 / Stage 2 / Stage 3", "Step 1 / Step 2 / Step 3", "Phase 01 / Phase 02 / Phase 03", "Pass One / Pass Two / Pass Three". Banned. The actual step content is the label. If you must show progression, use the verb-noun directly ("Install", "Configure", "Ship") not "Stage 1: Install".
|
|
665
|
-
|
|
666
|
-
**Pills, labels and version stamps**
|
|
667
|
-
* **NO pills/labels/tags overlaid on images.** No `<span>` overlays on photos with tags like `Brand · 02`, `PLATE · BRAND`, `Field notes - journal`. Either let the image speak alone, or add a caption directly below (outside the image).
|
|
668
|
-
* **NO photo-credit captions as decoration.** Strings like `Field study no. 12 · Ines Caetano`, `Plate 03 · House archive`, `Frame XII · 35mm` under stock/picsum images are pretentious. Photo credit is allowed ONLY when there is a real photographer being credited for a real photo (with permission). Otherwise: skip the caption or use a one-line functional caption ("The 6-quart, in Sage.").
|
|
669
|
-
* **NO version footers on marketing pages.** Footer strings like `v1.4.2`, `Build 0048`, `last sync 4s ago · main` are CLI / devtool fixtures, not landing-page content. Banned on marketing/landing/portfolio pages.
|
|
670
|
-
* **NO "Reservation 412 of 800"-style live-stock counters** as decoration. Only if the brief is explicitly a limited-run waitlist with real data.
|
|
671
|
-
|
|
672
|
-
**Decoration text strips**
|
|
673
|
-
* **NO decoration text strip at hero bottom.** Patterns like `BRAND. MOTION. SPATIAL.`, `TYPE / FORM / MOTION`, `DESIGN · BUILD · SHIP`, `ESTD. 2018 · LISBON · BRAND. MOTION. SPATIAL.` as a small mono-caps strip across the bottom of the hero are an agency-portfolio cliché. Banned by default. Only acceptable when the strip carries real, navigable links (sticky bottom nav) or real status info (cookie banner, build info on a docs site).
|
|
674
|
-
* **NO floating top-right sub-text in section headings.** Pattern: section has a giant left-aligned headline; in the top-right corner of the same section header there is a small explainer paragraph floating with no clear alignment to anything else. That floater is the Tell. Either put the sub-text directly under the headline, or build a clean 2-column header (left: headline, right: aligned body), but not a tiny corner paragraph.
|
|
675
|
-
|
|
676
|
-
**Lists, dividers and scoring**
|
|
677
|
-
* **NO `border-t` + `border-b` on every row of a long list / spec table.** Pick one (bottom-border between rows OR top-border above the group) and use it sparsely. A 10-row spec table with hairlines under each row is the laziest layout - see Section 4.9 for alternative UI components.
|
|
678
|
-
* **NO scoring/progress bars with filled background tracks** as comparison visuals. If you need to show "X out of Y" comparisons, prefer a number + small icon, or a tiny inline bar WITHOUT a background track. Big filled `bg-zinc-200` tracks with a partial fill on top are dashboard-UI clutter on a landing page.
|
|
679
|
-
|
|
680
|
-
**Locale, time, scroll cues**
|
|
681
|
-
* **Locale / city-name / time / weather strips are banned for 99% of briefs.** "Lisbon, working with founders" in the hero, "1200-690 Lisbon, Portugal" in the footer, "Lisbon 14:23 · 18°C" in the nav. These are agency-portfolio decoration tells. Allowed ONLY when: the brief explicitly describes a globally-distributed studio with timezone-relevant work, OR a travel-focused brand, OR a real-world physical venue. A single contact-address mention in the footer is fine; an atmospheric locale strip is not.
|
|
682
|
-
* **Scroll cues are banned.** `Scroll`, `↓ scroll`, `Scroll to explore`, `Scroll to walk through it`, animated mouse-wheel icons. If the user has not scrolled yet, they are looking at the hero. They know what scroll is. The bottom of the viewport does not need a label.
|
|
683
|
-
* **ZERO decorative status dots by default.** A coloured dot before nav items, before list rows, before badges, before status labels is a Tell. Only acceptable when conveying real semantic state (a live indicator on actual server status, a live availability flag) and limited to one per page section.
|
|
684
|
-
|
|
685
|
-
### 9.G EM-DASH BAN (the single most-violated Tell)
|
|
686
|
-
|
|
687
|
-
**Em-dash (`—`) is COMPLETELY banned.** It is the LLM's signature stylistic crutch and it is the #1 visual Tell in production tests. There is no "limited use" allowance, no "natural language frequency" allowance, no "in body copy is fine" allowance. None.
|
|
688
|
-
|
|
689
|
-
* **Banned in headlines.** Use a period or a comma.
|
|
690
|
-
* **Banned in eyebrows / labels / pills / button text / image captions / nav items.** Replace with line breaks, columns, or hairlines.
|
|
691
|
-
* **Banned in body copy.** Restructure the sentence: two sentences with a period, OR a comma, OR parentheses, OR a colon.
|
|
692
|
-
* **Banned in quote attribution.** Use a normal hyphen with spaces (` - `) or a line break + smaller-weight name.
|
|
693
|
-
* **Banned in en-dash form too (`–`) when used as a separator.** Date ranges (`2018-2026`) use a hyphen. Number ranges (`€40-80k`) use a hyphen.
|
|
694
|
-
|
|
695
|
-
The ONLY permitted dash characters on the page are:
|
|
696
|
-
* Regular hyphen `-` (for compound words, ranges, line dividers in markup)
|
|
697
|
-
* Minus sign in math (`-5°C`)
|
|
698
|
-
|
|
699
|
-
If your output contains a single `—` or `–` anywhere visible to the user, the output fails the Pre-Flight Check and must be rewritten.
|
|
700
|
-
|
|
701
|
-
This rule is non-negotiable. The agent has historically ignored em-dash limits when phrased as "use sparingly." The phrasing here is binary: zero em-dashes.
|
|
702
|
-
|
|
703
|
-
---
|
|
704
|
-
|
|
705
|
-
## 10. REFERENCE VOCABULARY (Pattern Names the Agent Should Know)
|
|
706
|
-
|
|
707
|
-
This is a vocabulary, not a library. The agent should KNOW these pattern names to communicate about them, design with them in mind, and reach for them when the design read calls for them. **Implementations and code sketches live in the Block Library (Section 12), which is populated iteratively.**
|
|
708
|
-
|
|
709
|
-
### Hero Paradigms
|
|
710
|
-
* **Asymmetric Split Hero** - Text on one side, asset on the other, generous white space.
|
|
711
|
-
* **Editorial Manifesto Hero** - Large type, no asset, almost-poster.
|
|
712
|
-
* **Video / Media Mask Hero** - Type cut out as mask over video background.
|
|
713
|
-
* **Kinetic-Type Hero** - Animated typography as the primary visual.
|
|
714
|
-
* **Curtain-Reveal Hero** - Hero parts on scroll like a curtain.
|
|
715
|
-
* **Scroll-Pinned Hero** - Hero stays pinned while content scrolls behind.
|
|
716
|
-
|
|
717
|
-
### Navigation & Menus
|
|
718
|
-
* **Mac OS Dock Magnification** - Edge nav, icons scale fluidly on hover.
|
|
719
|
-
* **Magnetic Button** - Pulls toward cursor.
|
|
720
|
-
* **Gooey Menu** - Sub-items detach like viscous liquid.
|
|
721
|
-
* **Dynamic Island** - Morphing pill for status / alerts.
|
|
722
|
-
* **Contextual Radial Menu** - Circular menu expanding at click point.
|
|
723
|
-
* **Floating Speed Dial** - FAB springing into curved secondary actions.
|
|
724
|
-
* **Mega Menu Reveal** - Full-screen dropdown, stagger-fade content.
|
|
725
|
-
|
|
726
|
-
### Layout & Grids
|
|
727
|
-
* **Bento Grid** - Asymmetric tile grouping (Apple Control Center).
|
|
728
|
-
* **Masonry Layout** - Staggered grid, no fixed row height.
|
|
729
|
-
* **Chroma Grid** - Borders / tiles with subtle animating gradients.
|
|
730
|
-
* **Split-Screen Scroll** - Two halves sliding in opposite directions.
|
|
731
|
-
* **Sticky-Stack Sections** - Sections that pin and stack on scroll.
|
|
732
|
-
|
|
733
|
-
### Cards & Containers
|
|
734
|
-
* **Parallax Tilt Card** - 3D tilt tracking mouse coordinates.
|
|
735
|
-
* **Spotlight Border Card** - Borders illuminate under cursor.
|
|
736
|
-
* **Glassmorphism Panel** - Frosted glass with inner refraction.
|
|
737
|
-
* **Holographic Foil Card** - Iridescent rainbow shift on hover.
|
|
738
|
-
* **Tinder Swipe Stack** - Physical card stack, swipe-away.
|
|
739
|
-
* **Morphing Modal** - Button expands into its own dialog.
|
|
740
|
-
|
|
741
|
-
### Scroll Animations
|
|
742
|
-
* **Sticky Scroll Stack** - Cards stick and physically stack.
|
|
743
|
-
* **Horizontal Scroll Hijack** - Vertical scroll → horizontal pan.
|
|
744
|
-
* **Locomotive / Sequence Scroll** - Video / 3D sequence tied to scrollbar.
|
|
745
|
-
* **Zoom Parallax** - Central background image zooming on scroll.
|
|
746
|
-
* **Scroll Progress Path** - SVG line drawing along scroll.
|
|
747
|
-
* **Liquid Swipe Transition** - Page transition like viscous liquid.
|
|
748
|
-
|
|
749
|
-
### Galleries & Media
|
|
750
|
-
* **Dome Gallery** - 3D panoramic gallery.
|
|
751
|
-
* **Coverflow Carousel** - 3D carousel with angled edges.
|
|
752
|
-
* **Drag-to-Pan Grid** - Boundless draggable canvas.
|
|
753
|
-
* **Accordion Image Slider** - Narrow strips expanding on hover.
|
|
754
|
-
* **Hover Image Trail** - Mouse leaves popping image trail.
|
|
755
|
-
* **Glitch Effect Image** - RGB-channel shift on hover.
|
|
756
|
-
|
|
757
|
-
### Typography & Text
|
|
758
|
-
* **Kinetic Marquee** - Endless text bands reversing on scroll.
|
|
759
|
-
* **Text Mask Reveal** - Massive type as transparent window to video.
|
|
760
|
-
* **Text Scramble Effect** - Matrix-style decoding on load / hover.
|
|
761
|
-
* **Circular Text Path** - Text curving along spinning circle.
|
|
762
|
-
* **Gradient Stroke Animation** - Outlined text with running gradient.
|
|
763
|
-
* **Kinetic Typography Grid** - Letters dodging the cursor.
|
|
764
|
-
|
|
765
|
-
### Micro-Interactions & Effects
|
|
766
|
-
* **Particle Explosion Button** - CTA shatters into particles on success.
|
|
767
|
-
* **Liquid Pull-to-Refresh** - Reload indicator like detaching droplets.
|
|
768
|
-
* **Skeleton Shimmer** - Shifting light reflection across placeholders.
|
|
769
|
-
* **Directional Hover-Aware Button** - Fill enters from cursor's exact side.
|
|
770
|
-
* **Ripple Click Effect** - Wave from click coordinates.
|
|
771
|
-
* **Animated SVG Line Drawing** - Vectors drawing themselves in real time.
|
|
772
|
-
* **Mesh Gradient Background** - Organic lava-lamp blobs.
|
|
773
|
-
* **Lens Blur Depth** - Background UI blurred to focus foreground action.
|
|
774
|
-
|
|
775
|
-
### Animation Library Choice
|
|
776
|
-
* **Motion (`motion/react`)** - default for UI / Bento / state-change motion.
|
|
777
|
-
* **GSAP + ScrollTrigger** - for full-page scrolltelling and scroll hijacks. Isolate in dedicated leaf components with `useEffect` cleanup.
|
|
778
|
-
* **Three.js / WebGL** - for canvas backgrounds and 3D scenes. Same isolation rule.
|
|
779
|
-
* **NEVER mix GSAP / Three.js with Motion in the same component tree.** They fight over the same frames.
|
|
780
|
-
|
|
781
|
-
---
|
|
782
|
-
|
|
783
|
-
## 11. REDESIGN PROTOCOL
|
|
784
|
-
|
|
785
|
-
This skill handles **greenfield builds AND redesigns**. Misclassifying the mode is the single biggest source of bad redesign output.
|
|
786
|
-
|
|
787
|
-
### 11.A Detect the Mode (first action)
|
|
788
|
-
* **Greenfield** - no existing site, or full overhaul approved. Dial baseline from Section 1.
|
|
789
|
-
* **Redesign - Preserve** - modernise without breaking the brand. Audit first, extract brand tokens, evolve gradually.
|
|
790
|
-
* **Redesign - Overhaul** - new visual language on top of existing content. Treat as greenfield for visuals; preserve content and IA.
|
|
791
|
-
|
|
792
|
-
If ambiguous, ask **once**: *"Should this redesign preserve the existing brand, or are we starting visually from scratch?"*
|
|
793
|
-
|
|
794
|
-
### 11.B Audit Before Touching
|
|
795
|
-
Document the current state before proposing changes:
|
|
796
|
-
* **Brand tokens** - primary / accent colors, type stack, logo treatment, radii.
|
|
797
|
-
* **Information architecture** - page tree, primary nav, key conversion paths.
|
|
798
|
-
* **Content blocks** - what exists, what's doing work, what's filler.
|
|
799
|
-
* **Patterns to preserve** - signature interactions, recognisable hero, copy voice.
|
|
800
|
-
* **Patterns to retire** - AI-slop tells, broken layouts, dead links, generic stock imagery, perf traps.
|
|
801
|
-
* **Dial reading of the existing site** - infer current `DESIGN_VARIANCE` / `MOTION_INTENSITY` / `VISUAL_DENSITY`. That's your starting point, not the baseline.
|
|
802
|
-
* **SEO baseline** - current ranking pages, meta titles, structured data, OG cards. **SEO migration is the #1 redesign risk.**
|
|
803
|
-
|
|
804
|
-
### 11.C Preservation Rules
|
|
805
|
-
* **Do not change information architecture** unless asked. Keep page slugs, anchor IDs, primary nav labels stable for SEO and muscle memory.
|
|
806
|
-
* **Extract brand colors before applying Section 4.2.** A brand that is already purple stays purple - apply the LILA RULE's override.
|
|
807
|
-
* **Preserve copy voice** unless asked for a rewrite. Visual modernisation ≠ content rewrite.
|
|
808
|
-
* **Honor existing accessibility wins.** Do not regress focus states, alt text, keyboard nav, contrast.
|
|
809
|
-
* **Respect existing analytics events.** Do not rename buttons, form fields, section IDs that downstream tracking depends on.
|
|
810
|
-
|
|
811
|
-
### 11.D Modernisation Levers (priority order)
|
|
812
|
-
Apply in order - stop when the brief is satisfied:
|
|
813
|
-
1. **Typography refresh** - biggest visual lift per unit of risk.
|
|
814
|
-
2. **Spacing & rhythm** - increase section padding, fix vertical rhythm.
|
|
815
|
-
3. **Color recalibration** - desaturate, unify neutrals, keep brand accent.
|
|
816
|
-
4. **Motion layer** - add `MOTION_INTENSITY`-appropriate micro-interactions to existing components.
|
|
817
|
-
5. **Hero & key-section recomposition** - restructure top-of-funnel using Section 10 vocabulary.
|
|
818
|
-
6. **Full block replacement** - only when the existing block is unsalvageable.
|
|
819
|
-
|
|
820
|
-
### 11.E Decision Tree: Targeted Evolution vs Full Redesign
|
|
821
|
-
* IA, content, and SEO sound → **targeted evolution** (Levers 1-4). ~70% of value at ~40% of risk.
|
|
822
|
-
* Visual debt is structural (broken IA, no design system, broken mobile) → **full redesign** with strict content preservation.
|
|
823
|
-
* Brand itself is changing → **greenfield**.
|
|
824
|
-
|
|
825
|
-
### 11.F What Never Changes Silently
|
|
826
|
-
Never modify without explicit user approval:
|
|
827
|
-
* URL structure / route slugs.
|
|
828
|
-
* Primary nav labels.
|
|
829
|
-
* Form field names or order (breaks analytics + autofill).
|
|
830
|
-
* Brand logo or wordmark.
|
|
831
|
-
* Existing legal / consent / cookie copy.
|
|
832
|
-
|
|
833
|
-
---
|
|
834
|
-
|
|
835
|
-
## 12. THE BLOCK LIBRARY (Contract - Implementations Land Here Iteratively)
|
|
836
|
-
|
|
837
|
-
The Reference Vocabulary (Section 10) names patterns. The Block Library implements them with real props, real motion specs, and real code sketches.
|
|
838
|
-
|
|
839
|
-
**Status:** schema defined here. Blocks will be added iteratively. Do not freelance new blocks without following this schema.
|
|
840
|
-
|
|
841
|
-
### 12.A File Location
|
|
842
|
-
```
|
|
843
|
-
skills/taste-skill/blocks/
|
|
844
|
-
hero/
|
|
845
|
-
asymmetric-split.md
|
|
846
|
-
editorial-manifesto.md
|
|
847
|
-
kinetic-type.md
|
|
848
|
-
...
|
|
849
|
-
feature/
|
|
850
|
-
bento-grid.md
|
|
851
|
-
sticky-scroll-stack.md
|
|
852
|
-
zig-zag.md
|
|
853
|
-
...
|
|
854
|
-
social-proof/
|
|
855
|
-
pricing/
|
|
856
|
-
cta/
|
|
857
|
-
footer/
|
|
858
|
-
navigation/
|
|
859
|
-
portfolio/
|
|
860
|
-
transition/
|
|
861
|
-
```
|
|
862
|
-
|
|
863
|
-
### 12.B Required Frontmatter
|
|
864
|
-
```yaml
|
|
865
|
-
---
|
|
866
|
-
name: asymmetric-split-hero
|
|
867
|
-
category: hero
|
|
868
|
-
dial_compatibility:
|
|
869
|
-
variance: [6, 10]
|
|
870
|
-
motion: [3, 10]
|
|
871
|
-
density: [2, 5]
|
|
872
|
-
when_to_use: "Landing pages with one strong asset and one strong message. Default hero for SaaS, agency, premium consumer."
|
|
873
|
-
not_for: "Editorial / manifesto launches where the message IS the design."
|
|
874
|
-
stack: ["react", "next", "tailwind", "motion"]
|
|
875
|
-
---
|
|
876
|
-
```
|
|
877
|
-
|
|
878
|
-
### 12.C Required Body Sections
|
|
879
|
-
1. **Visual sketch** - short ASCII or description of the layout.
|
|
880
|
-
2. **Props API** - the component's interface.
|
|
881
|
-
3. **Code sketch** - minimal working implementation (Server Component default, Client island for motion).
|
|
882
|
-
4. **Mobile fallback** - explicit collapse rules for `< 768px`.
|
|
883
|
-
5. **Motion variants** - one variant per `MOTION_INTENSITY` band (1-3, 4-7, 8-10). Reduced-motion fallback explicit.
|
|
884
|
-
6. **Dark-mode notes** - token strategy specific to this block.
|
|
885
|
-
7. **Anti-patterns** - common ways this block goes wrong.
|
|
886
|
-
8. **References** - links to real examples in production.
|
|
887
|
-
|
|
888
|
-
### 12.D Block-Library Discipline
|
|
889
|
-
* One block per file. No multi-block files.
|
|
890
|
-
* Every block must work standalone (drop it into a page, it renders).
|
|
891
|
-
* Every block must pass the Pre-Flight Check (Section 14).
|
|
892
|
-
* Blocks that depend on a design system from Section 2.A live under `blocks/<category>/<name>--<system>.md` (e.g. `feature/bento-grid--material.md`).
|
|
893
|
-
|
|
894
|
-
---
|
|
895
|
-
|
|
896
|
-
## 13. OUT OF SCOPE
|
|
897
|
-
|
|
898
|
-
This skill is NOT for:
|
|
899
|
-
* Dashboards / dense product UI / admin panels (use Fluent, Carbon, Atlassian, or Polaris from Section 2.A).
|
|
900
|
-
* Data tables (use TanStack Table or AG Grid).
|
|
901
|
-
* Multi-step forms / wizards (use Form-specific patterns; this skill won't make them better).
|
|
902
|
-
* Code editors (use Monaco / CodeMirror with their official skinning).
|
|
903
|
-
* Native mobile (use Apple HIG / Material directly).
|
|
904
|
-
* Realtime collab UIs (presence, cursors, OT-aware - different problem class).
|
|
905
|
-
|
|
906
|
-
If the brief is one of the above, **say so explicitly**, point to the right tool, and only apply this skill's marketing-page / about-page / landing-page parts to the surfaces where they apply.
|
|
907
|
-
|
|
908
|
-
---
|
|
909
|
-
|
|
910
|
-
## 14. FINAL PRE-FLIGHT CHECK
|
|
911
|
-
|
|
912
|
-
Run this matrix before outputting code. This is the last filter.
|
|
913
|
-
|
|
914
|
-
**THIS IS NOT OPTIONAL. Run every box. If any box fails, the output is not done.**
|
|
915
|
-
|
|
916
|
-
- [ ] **Brief inference** declared (Section 0.B one-liner)?
|
|
917
|
-
- [ ] **Dial values** explicit and reasoned from the brief, not silently using baseline?
|
|
918
|
-
- [ ] **Design system** chosen from Section 2 if applicable, or aesthetic labeled honestly?
|
|
919
|
-
- [ ] **Redesign mode** detected and audit performed (if applicable, Section 11)?
|
|
920
|
-
- [ ] **ZERO em-dashes (`—`) anywhere on the page.** Headlines, eyebrows, pills, body, quotes, attribution, captions, buttons, alt text. Zero. (Section 9.G - non-negotiable.)
|
|
921
|
-
- [ ] **Page Theme Lock**: ONE theme (light, dark, or auto) for the whole page. No section flips to inverted mode mid-page (Section 4.11)?
|
|
922
|
-
- [ ] **Color Consistency Lock**: one accent color used identically across all sections (Section 4.2)?
|
|
923
|
-
- [ ] **Shape Consistency Lock**: one corner-radius system applied consistently (Section 4.4)?
|
|
924
|
-
- [ ] **Button Contrast Check**: every CTA text is readable against its background (no white-on-white, WCAG AA 4.5:1)?
|
|
925
|
-
- [ ] **CTA Button Wrap**: no CTA label wraps to 2+ lines at desktop?
|
|
926
|
-
- [ ] **Form Contrast Check**: form inputs, placeholders, focus rings, labels all pass WCAG AA against the section background?
|
|
927
|
-
- [ ] **Serif discipline**: if a serif is used, it is NOT Fraunces or Instrument_Serif (or it is, with explicit brand justification)? Different serif from your previous project?
|
|
928
|
-
- [ ] **Premium-consumer palette check**: if the brief is premium-consumer (cookware / wellness / artisan / luxury), the palette is NOT the AI-default beige+brass+oxblood+espresso family? Different family from your previous premium-consumer project?
|
|
929
|
-
- [ ] **Italic descender clearance**: every italic word with `y g j p q` has `leading-[1.1]` min + `pb-1` reserve?
|
|
930
|
-
- [ ] **Hero fits the viewport**: headline ≤ 2 lines, subtext ≤ 20 words AND ≤ 4 lines, CTA visible without scroll, font scale planned around image?
|
|
931
|
-
- [ ] **Hero top padding**: max `pt-24` at desktop, hero content does not float halfway down the viewport?
|
|
932
|
-
- [ ] **Hero stack discipline**: max 4 text elements in hero (eyebrow OR brand strip, headline, subtext, CTAs)? No tiny tagline below CTAs, no trust micro-strip in hero?
|
|
933
|
-
- [ ] **EYEBROW COUNT (mechanical)**: count instances of `uppercase tracking` micro-labels above section headlines across all components. Count ≤ ceil(sectionCount / 3)? Hero counts as 1.
|
|
934
|
-
- [ ] **Split-Header Ban**: no "left big headline + right small explainer paragraph" pattern as a section header (vertical stack instead)?
|
|
935
|
-
- [ ] **Zigzag Alternation Cap**: no 3+ consecutive sections with the same image+text-split layout?
|
|
936
|
-
- [ ] **No Duplicate CTA Intent**: no two CTAs with the same intent ("Get in touch" + "Let's talk" both on page = Fail)?
|
|
937
|
-
- [ ] **Logo wall = logo only**: no industry / category labels printed below logos?
|
|
938
|
-
- [ ] **Bento Background Diversity**: at least 2-3 bento cells have real visual variation (image, gradient, pattern), not all white-on-white text cards?
|
|
939
|
-
- [ ] **"Used by / Trusted by" logo wall** lives UNDER the hero, not inside it, uses REAL SVG logos (Simple Icons / devicon) or generated SVG marks, NOT plain text wordmarks?
|
|
940
|
-
- [ ] **Copy Self-Audit**: every visible string re-read, no grammatically-broken or AI-hallucinated phrases ("free on its past" type) shipped?
|
|
941
|
-
- [ ] **Motion motivated**: every animation can be justified in one sentence (hierarchy / storytelling / feedback / state transition), no GSAP-for-show?
|
|
942
|
-
- [ ] **Marquee max-one-per-page**: no two horizontal marquees on the same page?
|
|
943
|
-
- [ ] **Navigation on ONE line** at desktop, height ≤ 80px?
|
|
944
|
-
- [ ] **Section-Layout-Repetition** check: no two sections share the same layout family (at least 4 different families across 8 sections)?
|
|
945
|
-
- [ ] **Bento has rhythm AND exact cell count** (N items → N cells, no empty cells in middle or at end)?
|
|
946
|
-
- [ ] **Long lists use the right UI component** (not default `<ul>` with `divide-y` for > 5 items - see Section 4.9 alternatives)?
|
|
947
|
-
- [ ] **Real images used** (gen-tool first, then Picsum-seed, then explicit placeholder slots) - NO div-based fake screenshots, NO hand-rolled decorative SVGs, NO pure-text minimalism?
|
|
948
|
-
- [ ] **No pills/labels overlaid on images** (no `Plate · Brand`, no `Field notes - journal`)?
|
|
949
|
-
- [ ] **No photo-credit captions as decoration** (`Field study no. 12 · Ines Caetano`)?
|
|
950
|
-
- [ ] **No version footers** (`v1.4.2`, `Build 0048`) on marketing pages?
|
|
951
|
-
- [ ] **No micro-meta-sentences** under eyebrows ("Each of these is a feature we ship today...")?
|
|
952
|
-
- [ ] **No decoration text strip at hero bottom** (`BRAND. MOTION. SPATIAL.`)?
|
|
953
|
-
- [ ] **No floating top-right sub-text** in section headings?
|
|
954
|
-
- [ ] **No scoring/progress bars with filled background tracks** as comparison visuals?
|
|
955
|
-
- [ ] **No locale / city-name / time / weather strips** unless brief is genuinely globally-distributed or place-focused?
|
|
956
|
-
- [ ] **No scroll cues** (`Scroll`, `↓ scroll`, `Scroll to explore`)?
|
|
957
|
-
- [ ] **No version labels in hero** (V0.6, BETA, INVITE-ONLY) unless the brief is a launch?
|
|
958
|
-
- [ ] **No section-numbering eyebrows** (`00 / INDEX`, `001 · Capabilities`, `06 · how it works`)?
|
|
959
|
-
- [ ] **No decorative dots** (zero by default, only for real semantic state)?
|
|
960
|
-
- [ ] **No `border-t` + `border-b` on every row** of long lists / spec tables?
|
|
961
|
-
- [ ] **Content density** sane: no 20-row data tables, no fake-precise specs without justification, ≤ 25-word sub-paragraphs by default?
|
|
962
|
-
- [ ] **Quotes ≤ 3 lines** of body, attribution clean (no em-dash)?
|
|
963
|
-
- [ ] **Motion claimed = motion shown**: if `MOTION_INTENSITY > 4`, page actually animates, not just claimed?
|
|
964
|
-
- [ ] **GSAP sticky-stack / horizontal-pan** implemented per Section 5.A / 5.B canonical skeleton (`start: "top top"`, `pin: true`, correct scrub)?
|
|
965
|
-
- [ ] **No `window.addEventListener('scroll')`** - using Motion `useScroll()` / ScrollTrigger / IntersectionObserver / CSS scroll-driven animations only?
|
|
966
|
-
- [ ] **Reduced motion** wrapped for everything `MOTION_INTENSITY > 3`?
|
|
967
|
-
- [ ] **Dark mode** tokens defined and tested in both modes?
|
|
968
|
-
- [ ] **Mobile collapse** explicit (`w-full`, `px-4`, `max-w-7xl mx-auto`) for high-variance layouts?
|
|
969
|
-
- [ ] **Viewport stability**: `min-h-[100dvh]`, never `h-screen`?
|
|
970
|
-
- [ ] **`useEffect` animations** have strict cleanup functions?
|
|
971
|
-
- [ ] **Empty / loading / error** states provided?
|
|
972
|
-
- [ ] **Cards omitted** in favor of spacing where possible?
|
|
973
|
-
- [ ] **Icons** from an allowed library only (Phosphor / HugeIcons / Radix / Tabler), no hand-rolled SVG paths?
|
|
974
|
-
- [ ] **Motion** isolated in client-leaf components with `'use client'` at the top, memoized?
|
|
975
|
-
- [ ] **No AI Tells** from Section 9 (Inter as default, AI-purple, three-equal cards, Jane Doe, Acme, "Quietly in use at")?
|
|
976
|
-
- [ ] **Core Web Vitals** plausibly hit (LCP < 2.5s, INP < 200ms, CLS < 0.1)?
|
|
977
|
-
- [ ] **One design system** per project (no Material + shadcn mixed)?
|
|
978
|
-
|
|
979
|
-
If a single checkbox cannot be honestly ticked, the page is not done. Fix it before delivering.
|
|
980
|
-
|
|
981
|
-
---
|
|
982
|
-
|
|
983
|
-
# APPENDICES - Real Source-Backed Reference Material
|
|
984
|
-
|
|
985
|
-
The sections below are vendored reference content. They give the agent real install commands, real canonical doc links, and real working starter snippets for each design system named in Section 2. Use them to ground decisions in production reality, not training-data fiction.
|
|
986
|
-
|
|
987
|
-
## Appendix A - Install Commands per Design System
|
|
988
|
-
|
|
989
|
-
```bash
|
|
990
|
-
# Material Web (Material 3)
|
|
991
|
-
npm install @material/web
|
|
992
|
-
|
|
993
|
-
# Fluent UI React (v9)
|
|
994
|
-
npm install @fluentui/react-components
|
|
995
|
-
|
|
996
|
-
# Fluent UI Web Components (framework-free)
|
|
997
|
-
npm install @fluentui/web-components @fluentui/tokens
|
|
998
|
-
|
|
999
|
-
# IBM Carbon
|
|
1000
|
-
npm install @carbon/react @carbon/styles
|
|
1001
|
-
|
|
1002
|
-
# Radix Themes
|
|
1003
|
-
npm install @radix-ui/themes
|
|
1004
|
-
|
|
1005
|
-
# shadcn/ui (open code, owned components)
|
|
1006
|
-
npx shadcn@latest init
|
|
1007
|
-
npx shadcn@latest add button card badge separator input
|
|
1008
|
-
|
|
1009
|
-
# Primer CSS (GitHub product/devtool UI)
|
|
1010
|
-
npm install --save @primer/css
|
|
1011
|
-
|
|
1012
|
-
# Primer Brand (GitHub marketing UI)
|
|
1013
|
-
npm install @primer/react-brand
|
|
1014
|
-
|
|
1015
|
-
# GOV.UK Frontend
|
|
1016
|
-
npm install govuk-frontend
|
|
1017
|
-
|
|
1018
|
-
# USWDS (US Web Design System)
|
|
1019
|
-
npm install uswds
|
|
1020
|
-
|
|
1021
|
-
# Atlassian Design System (Atlaskit)
|
|
1022
|
-
yarn add @atlaskit/css-reset @atlaskit/tokens @atlaskit/button @atlaskit/badge @atlaskit/section-message @atlaskit/card
|
|
1023
|
-
|
|
1024
|
-
# Bootstrap 5.3
|
|
1025
|
-
npm install bootstrap
|
|
1026
|
-
|
|
1027
|
-
# Shopify Polaris Web Components (Shopify apps only)
|
|
1028
|
-
# Add this to your app HTML head:
|
|
1029
|
-
# <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
|
|
1030
|
-
# <script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
|
|
1031
|
-
```
|
|
1032
|
-
|
|
1033
|
-
## Appendix B - Canonical Sources (read these before reinventing)
|
|
1034
|
-
|
|
1035
|
-
### Material Web
|
|
1036
|
-
- https://github.com/material-components/material-web
|
|
1037
|
-
- https://material-web.dev/theming/material-theming/
|
|
1038
|
-
- https://m3.material.io/develop/web
|
|
1039
|
-
|
|
1040
|
-
### Fluent UI
|
|
1041
|
-
- https://fluent2.microsoft.design/get-started/develop
|
|
1042
|
-
- https://fluent2.microsoft.design/components/web/react/
|
|
1043
|
-
- https://github.com/microsoft/fluentui
|
|
1044
|
-
- https://learn.microsoft.com/en-us/fluent-ui/web-components/
|
|
1045
|
-
|
|
1046
|
-
### Carbon
|
|
1047
|
-
- https://carbondesignsystem.com/
|
|
1048
|
-
- https://github.com/carbon-design-system/carbon
|
|
1049
|
-
- https://carbondesignsystem.com/developing/react-tutorial/overview/
|
|
1050
|
-
- https://carbondesignsystem.com/developing/web-components-tutorial/overview/
|
|
1051
|
-
|
|
1052
|
-
### Shopify Polaris
|
|
1053
|
-
- https://shopify.dev/docs/api/app-home/web-components
|
|
1054
|
-
- https://github.com/Shopify/polaris-react
|
|
1055
|
-
- https://polaris-react.shopify.com/components
|
|
1056
|
-
|
|
1057
|
-
### Atlassian
|
|
1058
|
-
- https://atlassian.design/get-started/develop
|
|
1059
|
-
- https://atlassian.design/components/button/examples
|
|
1060
|
-
- https://atlaskit.atlassian.com/packages/design-system/button/example/disabled
|
|
1061
|
-
- https://atlassian.design/tokens/design-tokens
|
|
1062
|
-
|
|
1063
|
-
### Primer
|
|
1064
|
-
- https://primer.style/
|
|
1065
|
-
- https://github.com/primer/css
|
|
1066
|
-
- https://github.com/primer/brand
|
|
1067
|
-
|
|
1068
|
-
### GOV.UK
|
|
1069
|
-
- https://design-system.service.gov.uk/components/button/
|
|
1070
|
-
- https://design-system.service.gov.uk/styles/layout/
|
|
1071
|
-
- https://github.com/alphagov/govuk-frontend
|
|
1072
|
-
|
|
1073
|
-
### USWDS
|
|
1074
|
-
- https://designsystem.digital.gov/documentation/developers/
|
|
1075
|
-
- https://designsystem.digital.gov/components/button/
|
|
1076
|
-
- https://designsystem.digital.gov/components/card/
|
|
1077
|
-
- https://github.com/uswds/uswds
|
|
1078
|
-
|
|
1079
|
-
### Bootstrap
|
|
1080
|
-
- https://getbootstrap.com/docs/5.3/layout/grid/
|
|
1081
|
-
- https://getbootstrap.com/docs/5.3/components/card/
|
|
1082
|
-
|
|
1083
|
-
### Tailwind
|
|
1084
|
-
- https://tailwindcss.com/docs/dark-mode
|
|
1085
|
-
- https://tailwindcss.com/blog/tailwindcss-v4
|
|
1086
|
-
|
|
1087
|
-
### Radix
|
|
1088
|
-
- https://www.radix-ui.com/themes/docs/components/theme
|
|
1089
|
-
- https://www.radix-ui.com/themes/docs/components/card
|
|
1090
|
-
- https://github.com/radix-ui/themes
|
|
1091
|
-
|
|
1092
|
-
### shadcn/ui
|
|
1093
|
-
- https://ui.shadcn.com/docs
|
|
1094
|
-
- https://ui.shadcn.com/docs/components/card
|
|
1095
|
-
- https://github.com/shadcn-ui/ui
|
|
1096
|
-
|
|
1097
|
-
### Native CSS / W3C standards
|
|
1098
|
-
- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/backdrop-filter
|
|
1099
|
-
- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-color-scheme
|
|
1100
|
-
- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion
|
|
1101
|
-
- https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout
|
|
1102
|
-
- https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Scroll-driven_animations
|
|
1103
|
-
- https://drafts.csswg.org/scroll-animations-1/
|
|
1104
|
-
|
|
1105
|
-
### Apple Liquid Glass (Apple platforms only)
|
|
1106
|
-
- https://developer.apple.com/design/human-interface-guidelines/materials
|
|
1107
|
-
- https://developer.apple.com/documentation/TechnologyOverviews/liquid-glass
|
|
1108
|
-
- https://developer.apple.com/documentation/TechnologyOverviews/adopting-liquid-glass
|
|
1109
|
-
- https://developer.apple.com/documentation/SwiftUI/Material
|
|
1110
|
-
|
|
1111
|
-
---
|
|
1112
|
-
|
|
1113
|
-
## Appendix C - Apple Liquid Glass: Honest Web Approximation
|
|
1114
|
-
|
|
1115
|
-
Do **not** treat random CSS snippets as official Apple Liquid Glass.
|
|
1116
|
-
|
|
1117
|
-
### What is official
|
|
1118
|
-
Apple documents Liquid Glass inside Apple's Human Interface Guidelines and Developer Documentation for **Apple platforms**. It is a dynamic material used across Apple platform UI. Apple's native implementation belongs to Apple platform APIs and system components, **not a public web CSS package**.
|
|
1119
|
-
|
|
1120
|
-
Relevant official docs:
|
|
1121
|
-
- Apple Human Interface Guidelines → Materials
|
|
1122
|
-
- Apple Developer Documentation → Liquid Glass
|
|
1123
|
-
- Apple Developer Documentation → Adopting Liquid Glass
|
|
1124
|
-
- SwiftUI → Material
|
|
1125
|
-
|
|
1126
|
-
### What is NOT official
|
|
1127
|
-
There is no `liquid-glass.css` from Apple for normal websites.
|
|
1128
|
-
|
|
1129
|
-
A web approximation can use:
|
|
1130
|
-
- `backdrop-filter`
|
|
1131
|
-
- transparent backgrounds
|
|
1132
|
-
- layered borders
|
|
1133
|
-
- highlight overlays
|
|
1134
|
-
- gradients
|
|
1135
|
-
- motion
|
|
1136
|
-
- strong contrast fallbacks
|
|
1137
|
-
|
|
1138
|
-
But that is **web glassmorphism / frosted-glass approximation**, not official Apple Liquid Glass. Label it as such in comments.
|
|
1139
|
-
|
|
1140
|
-
### Safer web approximation skeleton
|
|
1141
|
-
|
|
1142
|
-
```css
|
|
1143
|
-
.liquid-glass-web-approx {
|
|
1144
|
-
position: relative;
|
|
1145
|
-
isolation: isolate;
|
|
1146
|
-
overflow: hidden;
|
|
1147
|
-
border-radius: 999px;
|
|
1148
|
-
border: 1px solid rgb(255 255 255 / .32);
|
|
1149
|
-
background:
|
|
1150
|
-
linear-gradient(135deg, rgb(255 255 255 / .30), rgb(255 255 255 / .08)),
|
|
1151
|
-
rgb(255 255 255 / .12);
|
|
1152
|
-
backdrop-filter: blur(24px) saturate(180%) contrast(1.05);
|
|
1153
|
-
-webkit-backdrop-filter: blur(24px) saturate(180%) contrast(1.05);
|
|
1154
|
-
box-shadow:
|
|
1155
|
-
inset 0 1px 0 rgb(255 255 255 / .48),
|
|
1156
|
-
inset 0 -1px 0 rgb(255 255 255 / .12),
|
|
1157
|
-
0 18px 60px rgb(0 0 0 / .18);
|
|
1158
|
-
}
|
|
1159
|
-
|
|
1160
|
-
.liquid-glass-web-approx::before {
|
|
1161
|
-
content: "";
|
|
1162
|
-
position: absolute;
|
|
1163
|
-
inset: 0;
|
|
1164
|
-
z-index: -1;
|
|
1165
|
-
border-radius: inherit;
|
|
1166
|
-
background:
|
|
1167
|
-
radial-gradient(circle at 20% 0%, rgb(255 255 255 / .55), transparent 34%),
|
|
1168
|
-
linear-gradient(90deg, rgb(255 255 255 / .18), transparent 42%, rgb(255 255 255 / .14));
|
|
1169
|
-
pointer-events: none;
|
|
1170
|
-
}
|
|
1171
|
-
|
|
1172
|
-
.liquid-glass-web-approx::after {
|
|
1173
|
-
content: "";
|
|
1174
|
-
position: absolute;
|
|
1175
|
-
inset: 1px;
|
|
1176
|
-
border-radius: inherit;
|
|
1177
|
-
border: 1px solid rgb(255 255 255 / .14);
|
|
1178
|
-
pointer-events: none;
|
|
1179
|
-
}
|
|
1180
|
-
|
|
1181
|
-
@media (prefers-color-scheme: dark) {
|
|
1182
|
-
.liquid-glass-web-approx {
|
|
1183
|
-
border-color: rgb(255 255 255 / .18);
|
|
1184
|
-
background:
|
|
1185
|
-
linear-gradient(135deg, rgb(255 255 255 / .16), rgb(255 255 255 / .04)),
|
|
1186
|
-
rgb(15 23 42 / .42);
|
|
1187
|
-
box-shadow:
|
|
1188
|
-
inset 0 1px 0 rgb(255 255 255 / .22),
|
|
1189
|
-
0 18px 60px rgb(0 0 0 / .42);
|
|
1190
|
-
}
|
|
1191
|
-
}
|
|
1192
|
-
|
|
1193
|
-
@media (prefers-reduced-transparency: reduce) {
|
|
1194
|
-
.liquid-glass-web-approx {
|
|
1195
|
-
background: rgb(255 255 255 / .96);
|
|
1196
|
-
backdrop-filter: none;
|
|
1197
|
-
-webkit-backdrop-filter: none;
|
|
1198
|
-
}
|
|
1199
|
-
}
|
|
1200
|
-
```
|
|
1201
|
-
|
|
1202
|
-
**Important:** `prefers-reduced-transparency` has uneven browser support; test it. Always provide enough contrast even without blur.
|
|
1203
|
-
|
|
1204
|
-
---
|
|
1205
|
-
|
|
1206
|
-
**End of appendices.** Install commands above are reality anchors. The Apple Liquid Glass skeleton is a labeled approximation, not an Apple-issued package. For canonical docs per design system, consult the system's official docs (links in Section 2 plus Appendix B).
|
|
1
|
+
---
|
|
2
|
+
name: design-taste-frontend
|
|
3
|
+
description: >-
|
|
4
|
+
tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of
|
|
5
|
+
247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions
|
|
6
|
+
(idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict
|
|
7
|
+
no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use
|
|
8
|
+
this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site,
|
|
9
|
+
portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React,
|
|
10
|
+
Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated,
|
|
11
|
+
"AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other
|
|
12
|
+
site. Also for app screens: dashboards, admin and analytics views, settings, inboxes and other screens
|
|
13
|
+
people work in, with their own run and rules.
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# tasteskill v2
|
|
17
|
+
|
|
18
|
+
A page built by a model usually looks like the average of every page the model has seen: a centred
|
|
19
|
+
headline over three lines, a little label above it, a row of icon cards, a soft gradient, a few thin
|
|
20
|
+
rules and a monospace caption. Nothing in it is wrong and nothing in it was decided.
|
|
21
|
+
|
|
22
|
+
This skill replaces those defaults with decisions, in four ways:
|
|
23
|
+
|
|
24
|
+
1. **A script deals the directions, you choose among them.** Asked to invent a look, a model picks
|
|
25
|
+
the category default every time. `scripts/draw.mjs` deals three of twenty researched directions;
|
|
26
|
+
you choose the one that carries the subject's idea, and the script then deals its type system,
|
|
27
|
+
palette, hero and section compositions from a library distilled from 247 real sites.
|
|
28
|
+
2. **The idea comes from the subject.** In the study, what separated the best sites from the forgettable
|
|
29
|
+
ones was a concept taken from the thing itself, not the styling.
|
|
30
|
+
3. **A house style with no ornaments,** measured in a real browser by `scripts/inspect.mjs`, so the
|
|
31
|
+
rules are checked rather than hoped for.
|
|
32
|
+
4. **You look at what you made.** Screenshots at three widths, a juror's rubric, fix, look again.
|
|
33
|
+
|
|
34
|
+
One warning learned in testing. Taking the ornaments away is only half the job; a page that has lost its
|
|
35
|
+
labels, rules and cards and gained nothing in their place reads as thin, and blind jurors rightly prefer
|
|
36
|
+
a richer page with tells over an empty page without them. The other half is substance: type set
|
|
37
|
+
larger, whole fields of colour, real pictures of this subject's world (found or drawn), and every
|
|
38
|
+
section carrying its full content. The skill is built to give you that; do not trade it for restraint.
|
|
39
|
+
|
|
40
|
+
In the commands below `<skill>` is this skill's folder. Run them from the project's root, so the
|
|
41
|
+
working files land in `.taste-skill/` there. The scripts need Node 22+ and an installed Chrome, Edge
|
|
42
|
+
or Chromium, and install nothing. `assets.mjs` also needs network access; it uses no API keys.
|
|
43
|
+
|
|
44
|
+
## Page or app screen
|
|
45
|
+
|
|
46
|
+
Decide first which of two kinds of work this is.
|
|
47
|
+
|
|
48
|
+
- **A page** is read and scrolled: a landing page, a marketing or product site, a portfolio, an
|
|
49
|
+
event, a restaurant, a one-pager. It follows **the run** below.
|
|
50
|
+
- **An app screen** is worked in: a dashboard, an admin or analytics view, settings, billing, an inbox
|
|
51
|
+
or queue to work through, a wallet, a list with filters, an editor or builder. It follows
|
|
52
|
+
**`references/app-screens.md`**: its own run, its own draw (`draw.mjs --app`), its own house rules
|
|
53
|
+
(quiet borders, small labels and repeated panels are normal there; gradients, glows, icons in tinted
|
|
54
|
+
squares, rainbow charts and invented vanity numbers are not) and `inspect.mjs --app`. Read that file
|
|
55
|
+
whole before you start; the page run below does not apply.
|
|
56
|
+
|
|
57
|
+
A product site that shows its app is a page; the interface fragments on it follow the app-screen
|
|
58
|
+
rules for their insides. Deal the product's app style once, in its own folder, with the page's colours
|
|
59
|
+
and type kept:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
node <skill>/scripts/draw.mjs --app --kind <kind> --brief "<the product>" --keep palette,type --out .taste-skill/app
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
and build every fragment the page shows (the hero's live screen, a feature's crop, a chart) as a real
|
|
66
|
+
piece of that app: `assets/app.css` for its panels, tables and controls, `assets/charts.js` for its
|
|
67
|
+
charts, real data that adds up, one finding stated, cropped and scaled the way the page's blueprint
|
|
68
|
+
treats a picture. A fragment that looks like a working product is the strongest picture a software page
|
|
69
|
+
has; grey bars and lorem numbers are the weakest. When a request mixes both (a landing page and the
|
|
70
|
+
dashboard behind it), build each with its own run and one shared palette and typeface.
|
|
71
|
+
|
|
72
|
+
## The run
|
|
73
|
+
|
|
74
|
+
Do these in order. Steps 1–5 take a few minutes and decide whether the page is any good.
|
|
75
|
+
|
|
76
|
+
### 1. Read the brief and the project
|
|
77
|
+
|
|
78
|
+
Find out what is real: the subject, the audience, the one thing the page must get someone to do, the
|
|
79
|
+
stack, any existing brand (colours, fonts, logo), and above all **what imagery truly exists**: the
|
|
80
|
+
project's own photographs or product shots, a real interface that can be shown, an image generation
|
|
81
|
+
tool you can call, or nothing. Do not plan around pictures you do not have. Nothing of its own is
|
|
82
|
+
rarely nothing at all: the subject's city, street, materials and history are in open archives and
|
|
83
|
+
museums, free to use with a credit (step 6, `scripts/assets.mjs`).
|
|
84
|
+
|
|
85
|
+
If the request is vague, decide and state your reading in one line instead of asking. Ask only when a
|
|
86
|
+
missing fact blocks the work (for example, no product name).
|
|
87
|
+
|
|
88
|
+
Then **inventory the subject** in your notes: eight to twelve things that belong to this client and to
|
|
89
|
+
no competitor. Look for its name and what the name means; its address, door number, street and
|
|
90
|
+
neighbourhood, and what that place looks like (its tiles, signs, paint colours, typefaces on its shop
|
|
91
|
+
fronts, its light, its weather); the numbers in the brief (seats, rooms, minutes to the sea, the
|
|
92
|
+
price, the year); the constraint it lives with (only one batch a month, closed in winter, by
|
|
93
|
+
appointment); its materials and colours; its rituals and hours (the oven lit at five, the ferry at
|
|
94
|
+
seven); the printed things of its world (a timetable, a label, a ticket, a sign). This list is where
|
|
95
|
+
the idea comes from in step 4. In blind tests, the page that won each brief was built from an item on
|
|
96
|
+
such a list (the client's name and what it means, the street it stands in, the one constraint that
|
|
97
|
+
makes it what it is), and the pages that lost had a good composition with a category idea. The list
|
|
98
|
+
is also your picture search: each place, material and printed thing on it is a query for step 6.
|
|
99
|
+
|
|
100
|
+
### 2. Write the argument
|
|
101
|
+
|
|
102
|
+
Before any design, list the page as claims with their proof, one line per section, the way
|
|
103
|
+
`references/copy.md` §1 shows. The claims decide which sections exist and in what order. Delete any
|
|
104
|
+
section that has no claim. This is how you avoid the stock sequence of hero, logos, three features,
|
|
105
|
+
testimonial, pricing, call to action.
|
|
106
|
+
|
|
107
|
+
### 3. Draw the direction
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
node <skill>/scripts/draw.mjs --sector <sector> --brief "<one line about the subject>" \
|
|
111
|
+
--sections <roles in the order of your argument> [--tone <tone>] [--have <assets>] [--keep palette,type] \
|
|
112
|
+
--options 3
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
This deals three directions and prints a short summary of each. Hold each one against your inventory:
|
|
116
|
+
which way of composing can carry something only this client has? Choose that one, not the most
|
|
117
|
+
familiar, and write one line in your notes on why. In testing, a single random direction that did not
|
|
118
|
+
suit the subject was the commonest cause of a weak page. Then deal the full sheet:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
node <skill>/scripts/draw.mjs <the same arguments, without --options> --direction <chosen id>
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
- `--sector`: `node <skill>/scripts/draw.mjs --list sectors`. Pick the closest.
|
|
125
|
+
- `--sections`: roles from `--list roles` (features, showcase, how-it-works, testimonial, proof, stats,
|
|
126
|
+
pricing, faq, cta, footer, intro, about, work, gallery, list, contact). The hero is implied.
|
|
127
|
+
- `--tone` (optional): quiet, bold, warm, technical, playful, luxury, editorial. Only pass it when the
|
|
128
|
+
brief clearly asks for one.
|
|
129
|
+
- `--have`: assets that really exist, comma-separated: `photography` (the project's own photographs of
|
|
130
|
+
the place, people or work), `product-photo` (photographs of the specific product, or an image tool
|
|
131
|
+
that can make them), `product-ui` (real screenshots), `illustration`, `video`. Leave it out if you
|
|
132
|
+
have none: the draw then avoids compositions that depend on them and the sheet says how to fill
|
|
133
|
+
picture slots honestly (software shows its own interface built in HTML; a product with no photographs
|
|
134
|
+
is drawn and set among real pictures of its world, never a fake product shot). Pictures you will
|
|
135
|
+
find in the open collections are not the project's own; leave them out of `--have`.
|
|
136
|
+
- `--keep palette,type`: when the brand already fixes colours or typefaces. The draw then deals only
|
|
137
|
+
the composition, and you map the brand's values onto the roles.
|
|
138
|
+
|
|
139
|
+
The command prints a **direction sheet**. It is the art direction for this build:
|
|
140
|
+
|
|
141
|
+
- **Adopt it.** Do not blend it with the layout you would have made anyway. If it feels unfamiliar,
|
|
142
|
+
good: the familiar layout is the one this skill exists to prevent.
|
|
143
|
+
- Redraw one slot (`--redraw hero | type | palette | photos | scenes | section:<role> | direction`) only for a
|
|
144
|
+
reason you can state: it contradicts a stated brand constraint, needs an asset that does not exist,
|
|
145
|
+
or is a section that cannot hold the real content (next point). Never redraw to get something more
|
|
146
|
+
comfortable. Record every redraw in your report.
|
|
147
|
+
- When a dealt section cannot hold the real content (it compares three plans and there is one price;
|
|
148
|
+
it wants five quotations and there are none), do not bend the content to fit. List the others with
|
|
149
|
+
`--alternatives <role>`, pick the one whose assumptions match the content, and take it with
|
|
150
|
+
`--redraw section:<role>=<id>`.
|
|
151
|
+
- **Check the palette against the subject.** A dealt palette is a set of proportions (one ground, one
|
|
152
|
+
ink, one accent, fields) as much as a set of colours. If its colours fight the subject's own material
|
|
153
|
+
(candy pastels for a peat whisky, neon for a mountain hut), redraw the palette once; if the subject
|
|
154
|
+
has unmistakable colours of its own (its material, the paint of its street, the landscape outside
|
|
155
|
+
its windows), keep the dealt proportions and take the colours from the subject instead, and say so
|
|
156
|
+
in the report.
|
|
157
|
+
- Reprint it any time with `node <skill>/scripts/draw.mjs --show`. In a long session, re-read it before each
|
|
158
|
+
section you build.
|
|
159
|
+
|
|
160
|
+
### 4. Find the idea
|
|
161
|
+
|
|
162
|
+
The direction is a way of composing. The idea is what makes the page belong to this subject and no
|
|
163
|
+
other. Write this sentence in your notes and do not start building until both blanks are filled from
|
|
164
|
+
the subject itself:
|
|
165
|
+
|
|
166
|
+
> On this page, **[something that belongs to the subject]** becomes **[the device the direction calls for]**.
|
|
167
|
+
|
|
168
|
+
Places to look for the first blank:
|
|
169
|
+
|
|
170
|
+
- **Its output.** What does the thing produce? Put the real output on the page as material. (A camera
|
|
171
|
+
that prints poems delivered its copy as paper slips.)
|
|
172
|
+
- **Its object or shape.** What does it physically look like, in cross-section, in silhouette?
|
|
173
|
+
Enlarge it, crop it, make it the frame or the one motif.
|
|
174
|
+
- **Its name.** Can the letters hold a photograph, stack into a wall, split to two corners?
|
|
175
|
+
- **Its place.** Is there one view that makes someone want to be there?
|
|
176
|
+
- **Its ritual.** Is there a sequence the page can perform as it scrolls?
|
|
177
|
+
- **Its artefact.** What printed thing already exists in its world: ticket, menu, label, receipt,
|
|
178
|
+
invitation, folder, manual?
|
|
179
|
+
- **Its opposite.** Which other category owns the feeling this one lacks?
|
|
180
|
+
|
|
181
|
+
Fill the first blank from your inventory (step 1), not from the category. **The competitor test:** put
|
|
182
|
+
the nearest real competitor in the sentence (the bakery two streets away, another oak furniture maker,
|
|
183
|
+
another hut on the same mountain). If the sentence still works, the idea belongs to the category: a
|
|
184
|
+
loaf of bread is every bakery; the seven doors of the street this one is named after are only this one.
|
|
185
|
+
"Clean and modern" is not an idea. The sites the study's panel scored lowest were the ones whose idea
|
|
186
|
+
was recorded as "none beyond the standard formula".
|
|
187
|
+
|
|
188
|
+
**One live thing.** Give the page one thing the visitor can do, or that is different for each visit,
|
|
189
|
+
made from the idea: pick a wood and see the chair in it; type your name and see it cut in the
|
|
190
|
+
foundry's letters; set the loan and read the real monthly figure; see whether the hut's stove is lit
|
|
191
|
+
right now and how long until the last ferry; choose a size and see it against the room. In blind tests every winning page had one and the jurors named it first. Rules: it uses the subject's real content, it works on a phone with a thumb, it has a plain
|
|
192
|
+
fallback without script, it never blocks reading, and it is one thing, not a playground. It is
|
|
193
|
+
built in step 6 as part of the page, not added as motion in step 9.
|
|
194
|
+
|
|
195
|
+
**The scenes carry the idea too.** The scroll scenes on the sheet are devices waiting for a subject.
|
|
196
|
+
Decide what each one shows from your inventory before building: the fly-through passes through this
|
|
197
|
+
studio's own title cards, the route is the road this shipment really takes, the picture that opens to
|
|
198
|
+
the whole screen is the room the guest will wake up in. A scene filled with pictures that could belong
|
|
199
|
+
to anyone is a screensaver.
|
|
200
|
+
|
|
201
|
+
### 5. Write the words
|
|
202
|
+
|
|
203
|
+
Write the whole page as a copy deck (plain text) before markup, following `references/copy.md`:
|
|
204
|
+
|
|
205
|
+
- **Every headline fits in two lines or fewer at every width.** Do the arithmetic in copy.md §2 before
|
|
206
|
+
committing to a sentence: about 32 characters is safe everywhere at a confident size. The studied
|
|
207
|
+
gallery heroes have a median of 5 words and 32 characters.
|
|
208
|
+
- One supporting sentence, directly under the headline (32–48px below it) and shown with it, never
|
|
209
|
+
docked at the foot of the first screen or held back by an animation. When the headline is a name or
|
|
210
|
+
a figure of speech, this sentence says plainly what the thing is. One primary action, named for what
|
|
211
|
+
it does, as a real button on the first screen.
|
|
212
|
+
- **The first screen answers the visitor's first question in large type.** For an event: what it is,
|
|
213
|
+
when and where (the dates belong in the headline or at the second size, never only in small text).
|
|
214
|
+
For a product: what it is and what it costs or does. For a person: who and what they do. Every
|
|
215
|
+
section the visitor came for (the line-up, the menu, the rooms, the price) has its own heading and
|
|
216
|
+
its own place in the navigation.
|
|
217
|
+
- **Write the full content.** Every section the brief asks for delivers its information completely:
|
|
218
|
+
the whole menu with prices, each room with its own details, every speaker and talk, the price with
|
|
219
|
+
what it includes, an answer for each real question. Thin sections are the commonest reason a clean
|
|
220
|
+
page loses to a busier one.
|
|
221
|
+
- Sample details are expected where the brief leaves gaps (dish names, room names and rates, project
|
|
222
|
+
titles) so the design is seen at full density; list them in the report for the client to confirm.
|
|
223
|
+
Proof is never invented: no customers, quotes, reviews, press, logos or business statistics.
|
|
224
|
+
|
|
225
|
+
### 6. Build it, still
|
|
226
|
+
|
|
227
|
+
Build the page with motion switched off in your head; a page that needs animation to look finished is
|
|
228
|
+
not finished. Order of work:
|
|
229
|
+
|
|
230
|
+
1. **Tokens.** Colour and type roles from the sheet as CSS custom properties. Everything downstream
|
|
231
|
+
references tokens only. `<skill>/assets/base.css` is a neutral foundation you may start from (reset, token
|
|
232
|
+
names, fluid type steps, grid, focus and selection styles, the motion helpers); it has no look of
|
|
233
|
+
its own.
|
|
234
|
+
2. **The hero, exactly as the blueprint describes it,** at desktop and at phone width. Get the big
|
|
235
|
+
thing big and the small things small before anything else exists.
|
|
236
|
+
3. **Each section from its blueprint,** with this project's content. Keep the geometry, change the
|
|
237
|
+
subject. Neighbouring sections must not share a layout. **Carry the idea into every section,**
|
|
238
|
+
pricing, FAQ and footer included: the commonest failure in the study, even among good sites, is a
|
|
239
|
+
distinctive first screen followed by stock blocks.
|
|
240
|
+
4. **Imagery,** in this order of preference:
|
|
241
|
+
1. the project's own;
|
|
242
|
+
2. generated, if you have an image tool;
|
|
243
|
+
3. **real pictures of the subject's world from the open collections,** whenever an honest one
|
|
244
|
+
exists. Search them with `node <skill>/scripts/assets.mjs "<query>"` (Openverse, Wikimedia
|
|
245
|
+
Commons, the Art Institute of Chicago and the Met; only licences that allow commercial use, by
|
|
246
|
+
default). Search the inventory, not the category: its street in old postcards, an old map of the
|
|
247
|
+
neighbourhood, its material up close, its trade in engravings, a museum object of its kind, a
|
|
248
|
+
botanical plate, a star chart. Use them large and with intent: one archival photograph as the
|
|
249
|
+
hero, an engraving enlarged into the page's motif, the real map of the street as the contact
|
|
250
|
+
section. Look at each before choosing; `--get <ref>` downloads it into `assets/` and records
|
|
251
|
+
its source and licence, and `--credits` prints the credit line for the footer. A found picture
|
|
252
|
+
shows the world around the client and is never presented as the client's own product, room,
|
|
253
|
+
dish, person or team;
|
|
254
|
+
4. **drawn in code from the subject itself,** for what no honest picture exists of (its objects,
|
|
255
|
+
its tiles, its windows, its product's interface, made as one consistent flat graphic language in
|
|
256
|
+
the palette's real colours);
|
|
257
|
+
5. the photographs dealt on the sheet, only where an honestly generic picture fits (the sea for a
|
|
258
|
+
sea house), never as a stand-in for the subject;
|
|
259
|
+
6. type and colour alone.
|
|
260
|
+
|
|
261
|
+
When the project has footage or a real picture of its own process or product, the first screen
|
|
262
|
+
shows it, large (about 40% of the screen or more). Never write a sentence on the page about where
|
|
263
|
+
the pictures come from or what they are not ("none of these shows our bar"): a caption says what
|
|
264
|
+
the picture is, and the credit line sits small in the footer. A portfolio whose work is invented
|
|
265
|
+
for the brief draws each piece as a finished still of that work (its title card with its own type,
|
|
266
|
+
an end frame, a poster), with real detail, never as a pictogram of the client's product.
|
|
267
|
+
|
|
268
|
+
**The floor, which the inspector checks:** at least four real pictures on the page, usually six to
|
|
269
|
+
twelve (photographs, archival images, maps, engravings, footage, raster artwork; for software, its
|
|
270
|
+
cropped interface fragments count too). SVG drawings do not count toward the floor: draw what no
|
|
271
|
+
picture exists of, and still carry real pictures. Add one moving picture wherever an honest clip
|
|
272
|
+
exists: search it with `assets.mjs --video "<query>"` and use it as a muted loop with a poster
|
|
273
|
+
frame. Models skip pictures and footage because finding them is work; the page fails without them.
|
|
274
|
+
|
|
275
|
+
`references/imagery.md` covers searching, licences and credits, video, drawing, crops and treatments.
|
|
276
|
+
5. **The live thing** from step 4, built into the section where it proves the claim (often the hero
|
|
277
|
+
or the booking), with real content, a thumb-sized phone version and a plain fallback.
|
|
278
|
+
6. **The scroll scenes,** when the sheet deals them (section 9), each with the section it carries: the page's big
|
|
279
|
+
moments, the camera that flies through the work, the picture that opens to the whole screen, the
|
|
280
|
+
word that buckles under the scroll. Copy the shared stage and the scene's files from
|
|
281
|
+
`<skill>/assets/scenes/`, fill the scene with this project's own pictures and words, and set the
|
|
282
|
+
page's tokens so it takes the page's look. A scene is composition: it decides how long the page is
|
|
283
|
+
and what each screen shows, so it is built now and seen in every look round, not added at the end.
|
|
284
|
+
`references/scenes.md` says how to put one on a page, fill it, fit it and check it;
|
|
285
|
+
`assets/scenes/demo/<id>.html` is a working example of each.
|
|
286
|
+
7. **Fullness.** Look at each desktop screen as a poster: one dominant thing and the content it
|
|
287
|
+
carries. A screen that is mostly empty ground is an underbuilt section, not a rest; one deliberate
|
|
288
|
+
rest per page is the limit, and the inspector fails a page with two or more near-empty screens.
|
|
289
|
+
Running text is in the full ink at 16px or more; grey is for secondary notes.
|
|
290
|
+
8. **The frame.** The page has one pair of equal outer margins at every width, and every section uses
|
|
291
|
+
the width the page has set up: when its text sits in the left half, the right half holds its
|
|
292
|
+
picture, its second column, its list or its figure, never nothing. Asymmetry lives inside the grid,
|
|
293
|
+
never in the frame: a void is placed only when something closes it on the far side. No stretch of
|
|
294
|
+
the page taller than about half a screen holds nothing at all; sections are 120–240px apart on
|
|
295
|
+
desktop. Every section the visitor came for opens with a heading that names it, and the first
|
|
296
|
+
screen carries the page's title in an `h1`. These are what readers name first when a page looks
|
|
297
|
+
wrong ("no clear title", "random empty space", "everything is pushed to one side"), and the
|
|
298
|
+
inspector measures each of them.
|
|
299
|
+
9. **States and semantics.** Real links and buttons, visible focus, alt text, a phone layout that is
|
|
300
|
+
its own composition. Every control, the live thing included, works from the keyboard alone in
|
|
301
|
+
reading order and has an accessible name: its visible label, or `aria-label` when it shows only an
|
|
302
|
+
icon.
|
|
303
|
+
|
|
304
|
+
Read `references/type.md`, `references/colour.md` and `references/layout.md` when you need the detail
|
|
305
|
+
behind a decision; the laws below are the short form.
|
|
306
|
+
|
|
307
|
+
### 7. Gate
|
|
308
|
+
|
|
309
|
+
```bash
|
|
310
|
+
node <skill>/scripts/lint.mjs <source files or folder>
|
|
311
|
+
node <skill>/scripts/inspect.mjs <url or path/to/index.html>
|
|
312
|
+
node <skill>/scripts/scenes.mjs <url or path/to/index.html> # when the page has scroll scenes
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
`scenes.mjs` photographs every scroll scene at 0, 10 … 100% of its hold, on desktop and on a phone,
|
|
316
|
+
and the reduced-motion page; with scenes on the sheet, `inspect.mjs` also films the whole scroll
|
|
317
|
+
(`desktop-film-NN.jpg`). A scene that never started or rests on desktop is a `FAIL`.
|
|
318
|
+
|
|
319
|
+
`lint.mjs` scans source for banned patterns and stock phrases. `inspect.mjs` opens the page in a real
|
|
320
|
+
browser at 1440, 768 and 390 pixels, measures it (headline line counts, type sizes, fonts actually
|
|
321
|
+
loaded, colours, rules, shadows, gradients, contrast, overflow, and the frame: equal margins, sections
|
|
322
|
+
huddled on one side, blank stretches, the title, untitled sections, text against the screen edge) and
|
|
323
|
+
saves screenshots to `.taste-skill/inspect/`. Fix every `FAIL`. Treat each `WARN` as wrong unless you can defend it to a
|
|
324
|
+
designer in one sentence. Re-run until there are no `FAIL`s. Do not argue with the meter and do not
|
|
325
|
+
hide things from it. The inspector serves local files over a throwaway local server; if the page must
|
|
326
|
+
also open straight from the file system, open `index.html` that way once before you finish.
|
|
327
|
+
|
|
328
|
+
Inspect what the visitor receives. With a build step, run the last gate on the production build
|
|
329
|
+
(`vite build && vite preview`, `next build && next start`, or the built `index.html`), not only on the
|
|
330
|
+
dev server: minifiers and bundlers change what ships (one dropped a `backdrop-filter` that the dev
|
|
331
|
+
server showed). The inspector warns when it is looking at a dev server.
|
|
332
|
+
|
|
333
|
+
### 8. Look
|
|
334
|
+
|
|
335
|
+
Passing the gate means nothing banned was measured. It does not mean the page is good. Open the
|
|
336
|
+
screenshots the inspector lists (every viewport, with your image viewer or Read tool) and critique them
|
|
337
|
+
with `references/critique.md`: the fourteen passes, the Awwwards-weighted score, the caps. Write the critique
|
|
338
|
+
down in its format, fix the top three problems, run the inspector again, look again. Three rounds at
|
|
339
|
+
most.
|
|
340
|
+
|
|
341
|
+
Judge only the pictures. If a problem is visible in a screenshot, it is real, whatever the code says.
|
|
342
|
+
|
|
343
|
+
### 9. Move
|
|
344
|
+
|
|
345
|
+
Now build the motion layer. It is required, and it is more than one fade: the inspector counts the
|
|
346
|
+
elements that really move while the page loads and is scrolled, and fails a page under eight (it warns
|
|
347
|
+
under sixteen). Any scroll scenes are already built (step 6); around them the layer has four parts:
|
|
348
|
+
|
|
349
|
+
1. **The signature move** named on the sheet: one, done well (a dealt scene can be it).
|
|
350
|
+
2. **An entrance for the parts of every section:** the heading, then the text, then the picture,
|
|
351
|
+
staggered by 60–90ms, rising 16–32px with opacity, triggered once as the section enters. Not one
|
|
352
|
+
fade for the whole block, and never content that stays hidden if the script fails.
|
|
353
|
+
3. **Feedback on every control:** press, hover and focus on buttons, links, cards and the live thing.
|
|
354
|
+
4. **One moving picture:** a found clip as a muted loop, a slow scale or drift on a photograph, or a
|
|
355
|
+
scroll-linked move on the hero picture.
|
|
356
|
+
|
|
357
|
+
Transform and opacity only; every move has a `prefers-reduced-motion` fallback that keeps the content
|
|
358
|
+
and drops the travel. A move that changes the colour or the layout of whole screens (colour by
|
|
359
|
+
chapter, a pinned story) is part of the composition, so build it in step 6 and let every look round see
|
|
360
|
+
it. `references/motion.md` has the tokens and tested recipes. Then run the inspector once more and check
|
|
361
|
+
every screenshot for content that failed to appear.
|
|
362
|
+
|
|
363
|
+
### 10. Report
|
|
364
|
+
|
|
365
|
+
Do not report until all of these are true; each one was skipped in a test run that came out badly:
|
|
366
|
+
|
|
367
|
+
- `inspect.mjs` shows **0 FAIL** at 1440, 768 and 390, on the final version of the page.
|
|
368
|
+
- You opened every screenshot it listed after the last change, not only the first screen.
|
|
369
|
+
- With scroll scenes: `scenes.mjs` ran on the final page with no problems, and you read every sheet
|
|
370
|
+
(desktop, phone, reduced motion).
|
|
371
|
+
- A stranger reading the first screen for five seconds can say what this is and what to do.
|
|
372
|
+
- Every section has a heading; the margins match on both sides; no stretch of the page is empty.
|
|
373
|
+
- The critique of your last round is written down in the shape of `references/critique.md` §4.
|
|
374
|
+
|
|
375
|
+
Tell the user, briefly: the direction dealt (name and seed) and any redraws with reasons; the idea
|
|
376
|
+
sentence and the live thing; the final scores from your last critique round and what still falls short;
|
|
377
|
+
every found picture and clip with its title, creator, licence and source page (`assets.mjs --credits` prints
|
|
378
|
+
the list) and where its credit sits on the page; which bundled photographs and which drawings stand in
|
|
379
|
+
for photography (so they can be replaced); and any sample content that must be swapped before launch.
|
|
380
|
+
Do not claim a check you did not run.
|
|
381
|
+
|
|
382
|
+
## House rules
|
|
383
|
+
|
|
384
|
+
These hold on every build, whatever the direction. `inspect.mjs` measures them.
|
|
385
|
+
|
|
386
|
+
| Rule | Instead |
|
|
387
|
+
| --- | --- |
|
|
388
|
+
| **Headlines: two lines or fewer, at every width.** Every `h1`–`h6`, and the main line of the first screen whatever its tag. | Cut words. Then widen the measure. Size last. |
|
|
389
|
+
| **A clear title on the first screen**, in the page's one `h1`, and a heading on every section. | Say what this is: the name with what it does, the product with what it is for, the event with its date and place. |
|
|
390
|
+
| **Equal outer margins; no section huddled on one side** with the other half of the screen empty. | Close every void with something on its far side: the section's picture, a second column, a list, a figure. |
|
|
391
|
+
| **No blank stretches** taller than about half a screen. | The normal section gap. A deliberate rest is a placed picture or a field of colour, once per page. |
|
|
392
|
+
| **Statements are paragraphs.** An intro sentence or a quotation set large is marked up as `<p>` or `<blockquote>`, stays at statement size (36px or less on desktop, 24px on a phone) and runs to about 25 words, three lines. | Larger than that it is a headline and the two-line rule applies. In blind tests jurors read a 42px sentence over four lines as a four-line headline. |
|
|
393
|
+
| **No eyebrows.** No small label above a heading, no pill badge above the headline, no "New ·" chip. | Put the information in the heading or the first sentence, or drop it. |
|
|
394
|
+
| **No monospace** outside real code blocks. | The text face. Tabular figures where numbers align. |
|
|
395
|
+
| **No index numbering.** No 01 / 02 / 03, no (001), no "Step 2". | Order shown by position, size, or the words. A real `<ol>` if order matters. |
|
|
396
|
+
| **No thin rules.** No hairline dividers, no 1px outlined boxes, no grid lines, crosshairs or crop marks. | Space. A step in background tone. A change of scale. A filled shape. |
|
|
397
|
+
| **No gradients.** Not as backgrounds, not on buttons, not in text. | Flat colour, or a real photograph. A neutral scrim under text on a photo is the one exception. |
|
|
398
|
+
| **No shadows on things at rest.** No glows. | A tone step between surfaces. Shadows only on what truly floats: a menu, a dialog. |
|
|
399
|
+
| **No assistant palette.** No yellow-cream ground with terracotta or rust; no violet or indigo. | The dealt palette. |
|
|
400
|
+
| **No tiny uppercase letter-spaced labels.** | Sentence case at a readable size. |
|
|
401
|
+
| **No icon-topped feature cards, no rows of identical cards.** | The dealt section blueprint. |
|
|
402
|
+
| **No glass.** No backdrop blur panels, no floating pill navigation. | A plain bar: wordmark, a few links, one action. |
|
|
403
|
+
| **No emoji, no gradient blobs, no decorative shapes, no fake dashboards of grey bars.** | A real picture, a real interface fragment, or nothing. |
|
|
404
|
+
| **No styled accent word** in a headline (italic, serif, coloured, underlined). | One face, one colour. The words carry the emphasis. |
|
|
405
|
+
| **Two typefaces at most,** usually one. | The dealt type system. |
|
|
406
|
+
|
|
407
|
+
Three places keep their own conventions and are left alone by the inspector: real code in
|
|
408
|
+
`<pre>`/`<code>` (monospace is correct there), real tables and form fields (they may have lines), and
|
|
409
|
+
a real interface fragment whose root carries the attribute `data-ui` (the product's own borders and
|
|
410
|
+
menus; see `references/imagery.md` §7).
|
|
411
|
+
|
|
412
|
+
Why these, honestly. Some are what the study measured: among the 247 sites, those the panel scored
|
|
413
|
+
7.5 or higher used icon feature cards 1% of the time against 28% for sites under 6.5, pill badges 14%
|
|
414
|
+
against 34%, gradients 22% against 52%, shadows 24% against 48%, tiny tracked caps 16% against 57%.
|
|
415
|
+
Others are the owner's taste and go against current gallery fashion: monospace labels, index numbers
|
|
416
|
+
and hairline grids are actually *more* common on award sites than on weak ones, which is exactly why
|
|
417
|
+
generators imitate them and why they now read as costume. They are banned here without exception.
|
|
418
|
+
`references/tells.md` keeps the dated registry.
|
|
419
|
+
|
|
420
|
+
Removing ornament leaves space. Never fill it with another ornament. Fill it with scale (make the main
|
|
421
|
+
thing larger), with the full content, with a picture made for this subject, or with a field of flat
|
|
422
|
+
colour. Leave it empty on purpose once per page at most.
|
|
423
|
+
|
|
424
|
+
## Laws of the craft
|
|
425
|
+
|
|
426
|
+
Short form. Numbers are from the study unless marked as house style.
|
|
427
|
+
|
|
428
|
+
**Type**
|
|
429
|
+
- Two or three sizes do the visible work: one very large, one small, nothing in between. Median
|
|
430
|
+
headline-to-body ratio on the studied sites is 4.3; the best go far beyond (largest type: median
|
|
431
|
+
8.4vw on the top sites against 5.0vw on the weak ones).
|
|
432
|
+
- Display type: tracking -0.02 to -0.05em, leading 0.85–1.05. Text: 16–20px, leading 1.45–1.6,
|
|
433
|
+
45–75 characters per line.
|
|
434
|
+
- Five sizes on a page is the ceiling. One family is normal (a third of the studied sites); two is the
|
|
435
|
+
limit.
|
|
436
|
+
- Left-aligned by default. Centre at most one moment.
|
|
437
|
+
|
|
438
|
+
**Space**
|
|
439
|
+
- One grid, one pair of tight margins (16–32px), used everywhere; large things run to the edges. Text
|
|
440
|
+
blocks share two or three left edges on the whole page.
|
|
441
|
+
- Asymmetry inside the grid, never in the frame: the two outer margins are equal, and an off-centre
|
|
442
|
+
heading is answered by something at the far side of the grid.
|
|
443
|
+
- The gap between sections is clearly larger than any gap inside one: 120–240px on desktop (the study's median is about 240).
|
|
444
|
+
- Each section has a different composition from its neighbours; none is a card grid.
|
|
445
|
+
|
|
446
|
+
**Colour**
|
|
447
|
+
- One ground, one ink, one accent. The accent appears on the action and perhaps one other thing.
|
|
448
|
+
- Running text in the full ink. A page set in soft grey reads unfinished.
|
|
449
|
+
- Surfaces are separated by a small step in tone, never by a line or a shadow.
|
|
450
|
+
- A section may change the whole field colour. Nothing fades into anything.
|
|
451
|
+
|
|
452
|
+
**Imagery**
|
|
453
|
+
- One dominant image beats six small ones. On the top-scored sites the hero media covers at least half
|
|
454
|
+
the first screen 68% of the time.
|
|
455
|
+
- Same crop ratios, same treatment, square corners unless the direction says otherwise (73% of the
|
|
456
|
+
studied sites leave media square).
|
|
457
|
+
- No image is better than a placeholder, an icon, or an abstract shape. A picture drawn for this
|
|
458
|
+
subject, in its colours and with care, is better than either. A real picture of its world, found
|
|
459
|
+
and credited, is better still.
|
|
460
|
+
- Every found picture is downloaded into the project, credited on the page and listed in the report.
|
|
461
|
+
None is presented as the client's own.
|
|
462
|
+
- Nothing ever lies on top of a headline or a statement (the inspector fails it).
|
|
463
|
+
|
|
464
|
+
**Components**
|
|
465
|
+
- Buttons: flat, one fill colour, either square-cornered or fully round, decided once (top sites: 52%
|
|
466
|
+
square, 23% pill; the 9–16px "soft" radius is the weak-site default). Most strong heroes have no
|
|
467
|
+
button at all, or one.
|
|
468
|
+
- Navigation: wordmark, three to five plain links, one action. No bar chrome.
|
|
469
|
+
- A control explains how to use it by its form, its label and its place. When it seems to need a
|
|
470
|
+
sentence on how to operate it, redesign the control instead of adding the sentence. What a field
|
|
471
|
+
accepts is different. First remove the limit where you can: a date picker, or a parser that takes
|
|
472
|
+
any common format. A limit that remains, such as password rules or file type and size, stays visible
|
|
473
|
+
beside the field and is tied to it with `aria-describedby`.
|
|
474
|
+
- The footer is a designed close, not a sitemap: on most strong sites the name returns at full width.
|
|
475
|
+
|
|
476
|
+
## Special cases
|
|
477
|
+
|
|
478
|
+
**An existing brand or design system.** Pass `--keep palette,type`, map the brand's colours and faces
|
|
479
|
+
onto the roles, and take only composition from the draw. The house rules still apply; if the brand
|
|
480
|
+
itself requires a banned device (its logo sits in a gradient, its accent is violet), keep the brand
|
|
481
|
+
asset, say so in the report, and pass `--allow <rule>` to the inspector for that rule only.
|
|
482
|
+
|
|
483
|
+
**Redesign, restyle or review of an existing page or app screen.**
|
|
484
|
+
|
|
485
|
+
1. **Record the before.** Run the project as it is and inspect it into its own folder
|
|
486
|
+
(`inspect.mjs <url> --out .taste-skill/before`, with `--app` for an app screen) and lint its
|
|
487
|
+
source. Read the code: the framework, the styling method (Tailwind v3 or v4, CSS modules,
|
|
488
|
+
styled-components, plain CSS), the components, and what must survive: routes, forms, data,
|
|
489
|
+
behaviour, the brand's own assets.
|
|
490
|
+
2. **A review stops here.** Critique the before screenshots with `references/critique.md`, list the
|
|
491
|
+
findings with the inspector's measurements, and name the three changes that would move the page
|
|
492
|
+
most.
|
|
493
|
+
3. **Keep the stack, the content and what works.** No framework or styling-library migration; check the
|
|
494
|
+
dependency file before adding anything. A restyle keeps the layout and takes type, colour and
|
|
495
|
+
components from a dealt direction (`--keep` whatever the brand fixes); a redesign deals a full
|
|
496
|
+
direction and rebuilds the sections from its blueprints inside the existing components. Either way
|
|
497
|
+
proceed from step 2 of the run with the page's real content.
|
|
498
|
+
4. **Order of work, biggest effect for least risk:** type (faces and scale), colour (one ground, one
|
|
499
|
+
ink, one accent), the frame (margins, section rhythm, a title on the first screen and a heading on
|
|
500
|
+
every section), states (hover, focus, loading, empty, error), then the stock components (icon
|
|
501
|
+
cards, pill badges, gradient blobs, card grids) replaced by the dealt blueprints.
|
|
502
|
+
5. **Prove it.** Inspect again into `.taste-skill/after`, compare before and after at every width,
|
|
503
|
+
click through every link, form and menu that worked before, and report the before and after
|
|
504
|
+
measurements side by side.
|
|
505
|
+
|
|
506
|
+
**A component or a single section, not a page.** Skip the draw unless there is no direction to follow.
|
|
507
|
+
Match the surrounding design, apply the house rules and the laws, and still inspect the result.
|
|
508
|
+
|
|
509
|
+
**No checkout, no form backend.** The primary button goes to the real destination when the brief names
|
|
510
|
+
one. Otherwise it opens an email with a written subject and body (`mailto:` with the visitor's choices
|
|
511
|
+
filled in), or, for a shop, it points at `#checkout` and the report says it must be wired before
|
|
512
|
+
launch. Never fake a payment form.
|
|
513
|
+
|
|
514
|
+
**No Chrome or Node 22.** Run `lint.mjs` (Node 18+), take screenshots with whatever browser tool you
|
|
515
|
+
have, and critique those. Say in the report that the inspector could not run.
|
|
516
|
+
|
|
517
|
+
**No network.** If `assets.mjs` reaches no source, draw the pictures and say in the report that the
|
|
518
|
+
open collections could not be searched.
|
|
519
|
+
|
|
520
|
+
## Files
|
|
521
|
+
|
|
522
|
+
| File | Read it when |
|
|
523
|
+
| --- | --- |
|
|
524
|
+
| `references/app-screens.md` | Any dashboard, admin, settings or other app screen: its own run, rules, tokens and checks. |
|
|
525
|
+
| `references/copy.md` | Writing the argument and the copy deck (steps 2 and 5). The two-line arithmetic. |
|
|
526
|
+
| `references/type.md` | Setting type: scales, tracking, measure, loading fonts, pairing. |
|
|
527
|
+
| `references/colour.md` | Applying the palette: roles, proportions, tone steps, dark pages, contrast. |
|
|
528
|
+
| `references/layout.md` | Grid, margins, rhythm, section variety, navigation, footer, the phone composition. |
|
|
529
|
+
| `references/imagery.md` | Choosing, finding, crediting, cropping and treating pictures; what to do with none. |
|
|
530
|
+
| `references/motion.md` | Step 9. Budget, tokens, recipes, reduced motion. |
|
|
531
|
+
| `references/scenes.md` | Step 6, when the sheet deals scroll scenes: putting one on a page, filling, fitting, the phone, checking, the catalogue. |
|
|
532
|
+
| `references/critique.md` | Step 8. How to look, how to score, what to fix first. |
|
|
533
|
+
| `references/tells.md` | The dated registry of generated-page tells and what each is replaced by. |
|
|
534
|
+
| `references/research.md` | The study: method, numbers, what the best and worst sites do. Cite it, do not guess. |
|
|
535
|
+
| `scripts/draw.mjs` | Deals and reprints the direction; `--photos`, `--site <id>` for more references; `--app` deals an app style instead. |
|
|
536
|
+
| `scripts/assets.mjs` | Step 6: searches open collections for real pictures of the subject's world; `--get` downloads with the credit, `--credits` prints them. |
|
|
537
|
+
| `scripts/lint.mjs` · `scripts/inspect.mjs` | The gate. |
|
|
538
|
+
| `scripts/scenes.mjs` | The gate for scroll scenes: each scene at 0-100% of its hold, desktop, phone, reduced motion. |
|
|
539
|
+
| `assets/base.css` · `assets/base.js` | An optional neutral foundation to build on. |
|
|
540
|
+
| `assets/scenes/` | The scroll scenes: the shared stage (`stage.js`, `stage.css`) and, for each scene in the library, its `.js`, `.css` and a working demo page in `demo/`. |
|
|
541
|
+
| `assets/app.css` · `assets/charts.js` | For app screens: a neutral shell, panels, tables and controls, and small SVG charts drawn to the app rules. |
|
|
542
|
+
| `library/` | The data the draw reads: directions, heroes, sections, type systems, palettes, photographs, studied sites, motions, scroll scenes (`scenes.json`), and the app styles, shells and screen patterns (`app.json`). Do not read it whole; use the script. |
|