@ryuenn3123/agentic-senior-core 6.16.6 → 6.17.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.
Files changed (70) hide show
  1. package/.agents/plugins/agentic-senior-core/.codex-plugin/plugin.json +1 -1
  2. package/.agents/plugins/agentic-senior-core/commands/asc-develop.md +1 -1
  3. package/.agents/plugins/agentic-senior-core/commands/asc-develop.toml +2 -3
  4. package/.agents/plugins/agentic-senior-core/commands/asc-test.md +1 -2
  5. package/.agents/plugins/agentic-senior-core/commands/asc-test.toml +2 -3
  6. package/.agents/plugins/agentic-senior-core/commands/asc-ui.md +1 -1
  7. package/.agents/plugins/agentic-senior-core/commands/asc-ui.toml +2 -3
  8. package/.agents/plugins/agentic-senior-core/hooks/lib/known-ui-slop-patterns.json +5 -0
  9. package/.agents/plugins/agentic-senior-core/hooks/post-edit-enforce.js +70 -9
  10. package/.agents/plugins/agentic-senior-core/hooks/stop-verify-gate.js +148 -0
  11. package/.agents/plugins/agentic-senior-core/hooks.json +7 -0
  12. package/.agents/plugins/agentic-senior-core/plugin.json +1 -1
  13. package/.agents/plugins/agentic-senior-core/skills/asc/SKILL.md +7 -6
  14. package/.agents/plugins/agentic-senior-core/skills/asc/references/writing-skills.md +15 -0
  15. package/.agents/plugins/agentic-senior-core/skills/asc-develop/SKILL.md +43 -58
  16. package/.agents/plugins/agentic-senior-core/skills/asc-develop/references/execution-plans.md +43 -0
  17. package/.agents/plugins/agentic-senior-core/skills/asc-develop/references/subagent-orchestration.md +55 -0
  18. package/.agents/plugins/agentic-senior-core/skills/asc-test/SKILL.md +3 -1
  19. package/.agents/plugins/agentic-senior-core/skills/asc-test/references/systematic-debugging.md +32 -0
  20. package/.agents/plugins/agentic-senior-core/skills/asc-ui/SKILL.md +42 -82
  21. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/data-to-structure.md +96 -0
  22. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/responsive-and-copy.md +32 -0
  23. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/states-and-a11y.md +38 -0
  24. package/gemini-extension.json +1 -1
  25. package/package.json +1 -1
  26. package/plugin.yaml +1 -1
  27. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/accessibility.md +0 -102
  28. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/copy-i18n.md +0 -167
  29. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/browser-surfaces.md +0 -69
  30. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/color-surfaces.md +0 -81
  31. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/composition-patterns.md +0 -299
  32. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/motion.md +0 -55
  33. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/themes-catalog.md +0 -199
  34. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/typography.md +0 -54
  35. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/divergence.md +0 -168
  36. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/mobile-responsive.md +0 -115
  37. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/modes/experience.md +0 -31
  38. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/modes/genre-calibration.md +0 -93
  39. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/modes/operate.md +0 -83
  40. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/modes/persuade.md +0 -109
  41. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/modes/read.md +0 -47
  42. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/redesign-audit.md +0 -89
  43. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/reflexes.md +0 -59
  44. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/states-feedback.md +0 -148
  45. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-attio-dom.json +0 -5
  46. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-attio.png +0 -0
  47. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-cal-dom.json +0 -5
  48. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-cal.png +0 -0
  49. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-clerk-dom.json +0 -5
  50. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-clerk.png +0 -0
  51. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-dub-dom.json +0 -5
  52. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-dub.png +0 -0
  53. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-linear-dom.json +0 -5
  54. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-linear.png +0 -0
  55. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-marketplace-dom.json +0 -5
  56. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-marketplace.png +0 -0
  57. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-mintlify-dom.json +0 -5
  58. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-mintlify.png +0 -0
  59. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-raycast-dom.json +0 -5
  60. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-raycast.png +0 -0
  61. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-resend-dom.json +0 -5
  62. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-resend.png +0 -0
  63. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-stripe-dom.json +0 -5
  64. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-stripe.png +0 -0
  65. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-supabase-dom.json +0 -5
  66. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-supabase.png +0 -0
  67. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-tldraw-dom.json +0 -5
  68. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-tldraw.png +0 -0
  69. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-vercel-dom.json +0 -5
  70. package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/visuals/real-vercel.png +0 -0
@@ -1,167 +0,0 @@
1
- # UX Writing, Microcopy & Internationalization (i18n)
2
-
3
- UI microcopy is an operational tool, not marketing collateral. Every word on screen either reduces user uncertainty or costs attention.
4
-
5
- ---
6
-
7
- ## 1. The 50% Reduction Rule
8
-
9
- Draft the copy, then delete half the words without losing meaning. Remove polite throat-clearing, redundant labels, and ornamental adjectives.
10
-
11
- | Verbose / Conversational | Direct Operational Copy | Rationale |
12
- |---|---|---|
13
- | "In order to get started, please enter your email address below." | "Email address" | Input labels require no preamble. |
14
- | "Are you sure you want to delete this repository? This action cannot be undone." | "Delete `octocat/hello-world`? This permanently removes all code and history." | Name the exact target and concrete consequence. |
15
- | "We couldn't seem to find any results matching your search criteria." | "No results for \"billing\"." | State the outcome, mirror the query. |
16
- | "Successfully updated your preferences." | "Preferences saved." | Past participle, 2 words, passive verb eliminated. |
17
- | "Click here to view our comprehensive documentation." | "View documentation →" | Never write "click here"; state the destination. |
18
-
19
- ---
20
-
21
- ## 2. Action Controls: Verb + Noun Grammar
22
-
23
- Buttons and mutation triggers must name their concrete target. Never use ambiguous lone affirmations.
24
-
25
- - **Banned:** `Submit`, `OK`, `Yes`, `Proceed`, `Continue`, `Go`, `Done`.
26
- - **Enforced:** `Create project`, `Invite member`, `Deploy branch`, `Delete webhook`, `Export CSV`.
27
-
28
- Exception: Standard multi-step navigation controls in fixed wizards (`Back`, `Next`) where the step indicator supplies the context.
29
-
30
- ---
31
-
32
- ## 3. Arithmetic Copy Budgets & The Argument-First Protocol
33
-
34
- ### 3.1 Arithmetic Budgets
35
- Constraint is arithmetic; enforce before falling in love with a sentence:
36
- - **Hero Headline Budget:** Must fit in **two lines or fewer** across all viewports.
37
- - Mobile (390px): $\le 32$ characters ($\sim 4$–$5$ words).
38
- - Desktop (1280px): $\le 42$ characters ($\sim 5$–$6$ words).
39
- - Use `text-wrap: balance` and intentional `<br>` tags to avoid single-word orphans.
40
- - **Supporting Line Budget:** Exactly **1 sentence**, at most **22 words**.
41
- - Directly states concrete function and audience.
42
- - Never repeats or paraphrases headline words.
43
- - **First-Viewport Word Budget:** Maximum **80 words** total across the first screen.
44
-
45
- ### 3.2 The Argument-First Protocol
46
- Before writing any HTML/JSX markup, outline the page as a sequence of claims with verifiable proofs:
47
- ```text
48
- 1. Claim: Three-legged oak stool, made to order. → Proof: High-res macro photography of stool.
49
- 2. Claim: Each seat cut from single solid board. → Proof: 3 close-ups of continuous wood grain.
50
- 3. Claim: Shipped in 6 weeks with tracking. → Proof: Verifiable production stages schedule.
51
- 4. Claim: Costs $240, delivered by the maker. → Proof: Exact price figure + Order button.
52
- ```
53
- *Rule:* Any section that lacks a factual claim or verifiable proof is filler—delete it immediately.
54
-
55
- ---
56
-
57
- ## 4. AI Cadences & Marketing Buzzword Blacklist
58
-
59
- ### 4.1 Banned AI Cadence Formulas
60
- Language models fall into statistical average patterns; recognize and refuse them:
61
- 1. **The Mad-Lib:** *"The [AI-powered/next-gen] platform for modern teams."*
62
- 2. **The Tricolon:** *"Fast. Simple. Secure."* or *"Plan. Build. Ship."*
63
- 3. **The Rebuttal:** *"It’s not just a tool, it’s a workflow."* / *"More than a framework."*
64
- 4. **The Preamble Throat-Clearing:** *"In today’s fast-paced digital world..."* / *"Built for modern teams..."*
65
- 5. **The Em-Dash Habit:** Using multiple em-dashes (`—`) in a single paragraph. Use a full stop.
66
-
67
- ### 4.2 Banned Marketing Buzzwords
68
- The following adjectives and verbs are banned across all surfaces:
69
- `seamless`, `seamlessly`, `empower`, `empowering`, `robust`, `effortless`, `effortlessly`, `cutting-edge`, `game-changing`, `elevate`, `unlock`, `unleash`, `dive in`, `delightful`, `next-generation`, `supercharge`, `blazing-fast`.
70
-
71
- When tempted to write an adjective, state the measurable property instead:
72
- - Instead of: *"A robust, blazing-fast pipeline."*
73
- - Write: *"Builds complete in under 45 seconds with isolated caching."*
74
-
75
- ---
76
-
77
- ## 5. Actionable Error Messages & Recovery
78
-
79
- An operational error message must never produce a dead end or display raw internal stack traces. Every error must answer three questions:
80
- 1. **What failed:** Direct statement of the blocked action.
81
- 2. **Why:** Factual cause (if actionable and known).
82
- 3. **How to recover:** Concrete button or path to unblock the user.
83
-
84
- | Raw / Unhelpful Error | Actionable Engineering Copy | Recovery Path |
85
- |---|---|---|
86
- | "Error 413: Payload too large." | "File exceeds the 25MB limit." | "Choose a smaller file" CTA |
87
- | "Failed to connect to server." | "Unable to reach database. Changes saved locally." | "Retry connection" button |
88
- | "Invalid credentials." | "Incorrect password for user@example.com." | "Reset password →" link |
89
-
90
- ---
91
-
92
- ## 6. Single-Language Consistency & Localization
93
-
94
- Interfaces and developer communications must maintain strict language purity without robotic or literal translation awkwardness.
95
-
96
- ### 6.1 Strict Monolingual Surface
97
- Choose one language for the entire surface and enforce it across headings, labels, errors, and tooltips:
98
- - **English UI:** All copy, actions, and timestamps in English.
99
- - **Indonesian UI:** All copy, actions, and timestamps in natural, standard Indonesian (KBBI/PUEBI).
100
-
101
- ### 6.2 Codebase Lexicon Supremacy (Anti-Hallucinated Naming)
102
- Before naming navigation menus, section titles, table columns, or actions in an existing codebase, inspect the project's models, controllers, and view variables:
103
- - **Respect established domain terms:** Always adopt the exact nouns established in the repository's models, routes, and translations. Never substitute recognized project nouns with unprompted external synonyms.
104
- - Use the actual terminology the organization and developers already use in their schema and UI.
105
-
106
- ### 6.3 Ban Robot Translations & Meta-Jargon Parens
107
- In localized interface and review text:
108
- 1. **No clumsy literal translations of English layout terms:**
109
- - Do NOT translate *drawer* into awkward calques; write natural native labels (e.g. "panel samping" or "detail").
110
- - Do NOT translate *modal* literally; write natural functional terms (e.g. "dialog" or "popup").
111
- - Do NOT translate *hairline border* as literal anatomy; write "garis tipis 1px" or "garis pemisah".
112
- - Do NOT translate layout stages into literal theatrical terms; write "layout dua kolom" or "area utama".
113
- 2. **No parenthetical English jargon leaks:**
114
- - Never write sentences that append raw English terms in parentheses as translation glosses.
115
- - Write clear, natural localized prose without meta-framework disclaimers.
116
-
117
- ### 6.4 Ban Hybrid Neologisms
118
- Never prefix local grammatical affixes onto foreign language stems:
119
-
120
- | Hybrid Neologism (Banned) | Standard Native Alternative | Pure English Alternative |
121
- |---|---|---|
122
- | `di-submit` | `Dikirim` / `Diserahkan` | `Submitted` |
123
- | `meng-generate` | `Menghasilkan` / `Membuat` | `Generating` |
124
- | `di-cancel` | `Dibatalkan` | `Cancelled` |
125
- | `meng-handle` | `Menangani` | `Handling` |
126
- | `di-approve` | `Disetujui` | `Approved` |
127
- | `meng-update` | `Memperbarui` | `Updating` |
128
- | `di-delete` | `Dihapus` | `Deleted` |
129
- | `me-restore` | `Memulihkan` | `Restoring` |
130
-
131
- ---
132
-
133
- ## 7. Dynamic Text Expansion & Internationalization Layout
134
-
135
- Text length varies drastically between languages:
136
- - German and Dutch expand +20% to +35% compared to English.
137
- - Indonesian expands +15% to +30% for verb-rich phrases.
138
- - Japanese and Chinese are visually dense and vertically taller.
139
-
140
- ### 7.1 Layout Rules for Expanding Strings
141
- 1. **Never set fixed widths on action buttons:**
142
- ```html
143
- <!-- BANNED: clips or overflows in German/Indonesian -->
144
- <button class="w-[120px] truncate">Save settings</button>
145
-
146
- <!-- ENFORCED: content-driven width with min-width safety -->
147
- <button class="min-w-[5rem] px-4 py-2">Save settings</button>
148
- ```
149
-
150
- 2. **Support multi-line wrapping for headings and table headers:**
151
- - Avoid `white-space: nowrap` on containers holding localized strings unless horizontally scrolling is explicitly designed.
152
- - Use `hyphens: auto` or flex wrapping on dense metric cards.
153
-
154
- 3. **Isolate placeholders and interpolated values:**
155
- - Never assemble sentences by concatenating translated strings:
156
- ```javascript
157
- // BANNED: grammar breaks in right-to-left or verb-final languages
158
- const msg = t("Deleted") + " " + count + " " + t("items");
159
-
160
- // ENFORCED: parameterized translation tokens
161
- const msg = t("deleted_items_count", { count });
162
- ```
163
-
164
- 4. **Numeric and Date Formatting:**
165
- - Use `Intl.NumberFormat` and `Intl.DateTimeFormat` with the active locale.
166
- - Never hardcode date patterns (`MM/DD/YYYY` fails in locales expecting `DD/MM/YYYY` or `YYYY-MM-DD`).
167
-
@@ -1,69 +0,0 @@
1
- # Craft: Themed Browser Surfaces
2
-
3
- Grounded in: Impeccable Browser Surfaces Standard and Web Platform Craft.
4
-
5
- > **Why This Matters:** The parts of the viewport you did not author still carry the design. Text selection, input carets, custom scrollbars, and focus rings all ship with unstyled browser defaults that belong to no design system. Theming these surfaces from the project palette is the clearest signal of intentional human craft.
6
-
7
- ---
8
-
9
- ## 1. Text Selection Highlight
10
-
11
- - **Theme the Selection:**
12
- - Standard browser selection (harsh electric blue) frequently clashes with custom brand palettes.
13
- - Apply semantic selection tokens matching the brand accent:
14
- ```css
15
- ::selection {
16
- background-color: var(--primary);
17
- color: var(--primary-foreground);
18
- }
19
- ```
20
- ```html
21
- <!-- Tailwind root or body -->
22
- <body class="selection:bg-primary selection:text-primary-foreground">
23
- ```
24
-
25
- ---
26
-
27
- ## 2. Form Carets & Native Focus
28
-
29
- - **Input Caret Color:**
30
- - Style the text cursor to match the primary brand token:
31
- ```css
32
- input, textarea {
33
- caret-color: var(--primary);
34
- }
35
- ```
36
- - **Consistent Focus Visible:**
37
- - Never let the browser default blue outline show on interactive elements:
38
- ```css
39
- :focus-visible {
40
- outline: 2px solid var(--ring);
41
- outline-offset: 2px;
42
- }
43
- ```
44
-
45
- ---
46
-
47
- ## 3. Custom Scrollbar Theming
48
-
49
- - **Subtle Scrollbars for Overflow Containers:**
50
- - Default browser scrollbars on Windows/Linux are bulky and intrusive.
51
- - Style internal scroll containers (`overflow-y-auto`, `overflow-x-auto`) with sleek, low-contrast scrollbars:
52
- ```css
53
- .custom-scrollbar {
54
- scrollbar-width: thin;
55
- scrollbar-color: var(--border) transparent;
56
- }
57
- .custom-scrollbar::-webkit-scrollbar {
58
- width: 6px;
59
- height: 6px;
60
- }
61
- .custom-scrollbar::-webkit-scrollbar-thumb {
62
- background-color: var(--border);
63
- border-radius: 9999px;
64
- }
65
- .custom-scrollbar::-webkit-scrollbar-track {
66
- background: transparent;
67
- }
68
- ```
69
-
@@ -1,81 +0,0 @@
1
- # Craft: Color Systems & Surface Elevation
2
-
3
- Grounded in: Apple HIG, Google Material Design 3, and Refactoring UI Color Strategies.
4
-
5
- ---
6
-
7
- ## 1. Token-First Color Architecture
8
-
9
- - **Semantic Tokens Only:**
10
- - Every surface, border, and text color must resolve through declared CSS variables or semantic framework tokens:
11
- - Backgrounds: `bg-background`, `bg-card`, `bg-muted`, `bg-popover`.
12
- - Text: `text-foreground`, `text-muted-foreground`, `text-primary-foreground`.
13
- - Borders: `border-border`, `border-input`, `border-primary`.
14
- - **Zero Raw Hex Literals in Markup:** Never write inline hex values (`#6366f1`, `#3b82f6`) or arbitrary utility classes (`bg-blue-600`) outside the root token definition.
15
-
16
- - **The Single Neutral Family Law (Anti-Muddy Surfaces):**
17
- - Never mix cool-tinted grays (e.g. Tailwind `slate-*`, with blue undertones) and warm-tinted grays (e.g. `stone-*`, with yellow/brown undertones) on the same screen. Combining `slate-900` text with `stone-50` backgrounds creates a dirty, mismatched optical surface.
18
- - Choose one neutral temperature matching the project's primary brand:
19
- - Warm brands (warm green, brown, amber, terracotta) $\to$ pair strictly with `stone` or neutral warm tones.
20
- - Cool brands (navy, cobalt, cyan, indigo) $\to$ pair strictly with `slate` or cool zinc.
21
- - Pure monochromatic / minimal brands $\to$ pair with neutral `zinc` or `gray`.
22
-
23
- ---
24
-
25
- ## 2. The 60-30-10 Distribution Rule
26
-
27
- - **60% Dominant Neutral Surface:**
28
- - The canvas base floor (tinted neutral like slate, zinc, or warm stone—never dead `#000000` or sterile `#ffffff`).
29
- - **30% Structural Neutral Containers:**
30
- - Cards, table backgrounds, navigation headers, sidebars, and divider lines.
31
- - **10% Purposeful Accent:**
32
- - The dedicated brand accent hue.
33
- - **Accent Exclusivity:** Accent color is reserved strictly for interactive affordances: Primary CTA button, active navigation indicator, unread dot, selected checkbox.
34
- - **Forbidden:** Never use the accent color as background wallpaper, card borders, or decorative section dividers.
35
- - **Full-Field Grounding (Anti-Sterile Surface):**
36
- - To prevent the "sterile white void" trap, at least one major functional region (the Hero Stage, the Signature Canvas, or the Master Header) must own a deep, purposeful surface field (e.g. deep midnight grounding, rich brand tint, or dark canvas container).
37
- - This establishes an optical center of gravity, preventing the page from looking like an unstyled wireframe.
38
-
39
- ---
40
-
41
- ## 3. Surface Elevation & The "Ghost Card" Ban
42
-
43
- - **Stepped Tonal Elevation:**
44
- - Build depth through background tone steps rather than heavy drop shadows:
45
- - *Base Canvas:* `bg-background` (Level 0)
46
- - *Containers & Cards:* `bg-card` (Level 1)
47
- - *Recessed Inset Wells (Search bars, secondary filters, code blocks):* `bg-muted/50`
48
- - **Declare Elevation Once (Ban The Ghost Card):**
49
- - Never apply both a distinct 1px border AND a wide, blurry drop shadow to the same container (`border border-slate-200 shadow-lg`). This creates an unnatural "ghost card".
50
- - Choose one clear depth language:
51
- - *Border-Driven:* Crisp 1px hairline border with alpha (`border-border/60`) and zero or minimal shadow (`shadow-xs`).
52
- - *Shadow-Driven:* Floating elevation (`shadow-md`) with borderless or subtle color shift.
53
- - **Tinted Secondary Text on Colored Surfaces:**
54
- - When placing secondary text on a colored or dark surface, tint the text using the parent background hue or foreground token (`text-primary-foreground/70`).
55
- - **Never use neutral gray text (`text-slate-400`) on a saturated or colored background.** It produces a muddy, dirty optical illusion.
56
-
57
- ---
58
-
59
- ## 4. Metric Displays & Scorecards
60
-
61
- - **Integrated Layout:** Never place an isolated white box with a thin border floating inside an already white or light header canvas.
62
- - **Anchor Into Layout Chrome:**
63
- - Integrate scorecards directly into the identity header rail or stage banner using a unified divider (`border-l border-border/80 pl-6`) or structural inset well (`bg-muted/40`).
64
- - **Semantic Tinting for Evaluation Scores:**
65
- - When communicating aggregate grades (e.g. `84.20 / 100`, Rank B):
66
- - Background: subtle semantic tint (`bg-emerald-500/10` or `bg-slate-500/10`).
67
- - Border: matching tinted hairline (`border border-emerald-500/20`).
68
- - Typography: tabular numbers (`font-mono tabular-nums`) with clear contrast ($Display \ge 3.5\times Body$).
69
- - Always position the grading scale key (e.g. `A > 85, B 71-85`) in immediate secondary proximity as muted metadata.
70
-
71
- ---
72
-
73
- ## 5. Inline Notifications & Status Banners
74
-
75
- - **Structured Containers:** Warning notes, disclaimers, or temporary state alerts must reside in clear semantic containers, never dumped as raw floating text between layout sections.
76
- - **Notification Requirements:** Every alert must reside in a structured callout container:
77
- - Container: 1px hairline border with matching light background tint (e.g. `border border-amber-500/30 bg-amber-500/10 rounded-md p-3`).
78
- - Icon Anchor: Dedicated semantic SVG icon (alert circle, triangle) aligned with first line of text.
79
- - Placement: Positioned immediately above or inside the data table/form it modifies, establishing unmistakable contextual binding.
80
-
81
-
@@ -1,299 +0,0 @@
1
- # Concrete UI Composition Patterns
2
-
3
- > **Core Invariant:** Do not rely on abstract prohibition lists. Modern models build high-craft interfaces by pattern-matching against authentic, human-designed DOM compositions and visual assets. Use the real-world reverse-engineered benchmarks below and structural archetypes instead of enclosing every section in a `1px` border wireframe box.
4
-
5
- ---
6
-
7
- ## 0. Real-World Live Benchmarks (Extracted via REA)
8
-
9
- The `references/visuals/` directory contains authentic, human-designed production websites reverse-engineered from the live web using REA (`capture_browser_scenario`). Each entry includes a **viewport screenshot (PNG)** for visual-spatial calibration and the **rendered DOM structure (JSON)** for class tokens and layout hierarchies:
10
-
11
- | Target Domain | Visual Reference (Screenshot) | Rendered DOM Structure | Key Design Traits to Adopt |
12
- | :--- | :--- | :--- | :--- |
13
- | **Developer Infra / Dark Editorial** | `references/visuals/real-resend.png` | `references/visuals/real-resend-dom.json` | High-contrast serif/sans display typography, delicate lighting gradient rays, minimal pill announcement, solid primary + ghost secondary actions. |
14
- | **Analytics & Data Dashboards** | `references/visuals/real-dub.png` | `references/visuals/real-dub-dom.json` | Subtle light grid canvas, embedded live dashboard stage, large bold KPI numbers (`$210,429.00`), spline chart rhythm, tabbed filter pills. |
15
- | **CRM & Relational Operations** | `references/visuals/real-attio.png` | `references/visuals/real-attio-dom.json` | Windowed desktop console frame, quick actions search bar with `⌘K`, multi-filter table density, minimal prompt input. |
16
- | **Authentication & Forms** | `references/visuals/real-clerk.png` | `references/visuals/real-clerk-dom.json` | Bounded form cards (`max-w-md`), multi-tenancy switcher tabs, OAuth SSO buttons, clean single-line inputs with generous tap targets. |
17
- | **Documentation & API Reference** | `references/visuals/real-mintlify.png` | `references/visuals/real-mintlify-dom.json` | Dual-rail navigation tree, section guide cards, language switcher pills, floating assistant action button. |
18
- | **Booking & Scheduling Flow** | `references/visuals/real-cal.png` | `references/visuals/real-cal-dom.json` | Playful bold typography with inline status badges, dual Microsoft/Google SSO buttons, embedded booking calendar mockup. |
19
- | **Storefront & App Catalog** | `references/visuals/real-marketplace.png` | `references/visuals/real-marketplace-dom.json` | Sidebar category filters, search toolbar, discrete integration cards with verified badges and tags, tabbed recommendation lists. |
20
- | **Collaborative Canvas & Studio** | `references/visuals/real-tldraw.png` | `references/visuals/real-tldraw-dom.json` | Receding full-bleed canvas chrome, floating bottom utility dock, minimal top-right palette/stroke controller, clean viewport zoom indicator. |
21
- | **Command Centers & Launchers** | `references/visuals/real-raycast.png` | `references/visuals/real-raycast-dom.json` | Obsidian dark background, directional accent glow, pill search/action bar, clean monospace system notes. |
22
- | **Cloud Databases & Platforms** | `references/visuals/real-supabase.png` | `references/visuals/real-supabase-dom.json` | Asymmetric 2-column hero split, signature accent color (emerald), capability feature grid with checkmarks and code pills. |
23
- | **Product Craft & Philosophy** | `references/visuals/real-linear.png` | `references/visuals/real-linear-dom.json` | Disciplined whitespace, editorial typography contrast, subtle geometric hairline accents, no unearned visual clutter. |
24
- | **High-Impact Brand Stage** | `references/visuals/real-vercel.png` | `references/visuals/real-vercel-dom.json` | Central geometric focal point, 3-line manifesto typography, high-contrast monochrome customer logo proof. |
25
- | **Enterprise Infrastructure** | `references/visuals/real-stripe.png` | `references/visuals/real-stripe-dom.json` | Fluid signature mesh gradients, prominent primary CTA with arrow, dual-action row with Google SSO. |
26
-
27
- When constructing or redesigning a surface, inspect the matching `references/visuals/real-*.png` via `read_file` to ground visual proportions (padding, font scaling, surface elevation) on real human craft.
28
-
29
- ---
30
-
31
- ## Pattern 1: Public Institutional / Product Hero (Bold Ground + Focused Action)
32
-
33
- *Use for: Public landing pages, civic platforms, institutional gateways, product launch.*
34
- *Key Traits: High-contrast typography scale, 1 primary action panel, no generic pill kickers, authentic brand presence.*
35
-
36
- ```html
37
- <section class="relative overflow-hidden bg-zinc-900 text-zinc-100 py-20 lg:py-28">
38
- <div class="max-w-6xl mx-auto px-6">
39
- <div class="grid grid-cols-1 lg:grid-cols-12 gap-12 lg:gap-16 items-center">
40
-
41
- <!-- Left: Assertive Narrative (7 cols) -->
42
- <div class="lg:col-span-7 space-y-6">
43
- <h1 class="text-4xl sm:text-5xl lg:text-6xl font-extrabold tracking-tight text-white leading-[1.08]">
44
- Reliable Verification for Regional Operations.
45
- </h1>
46
- <p class="text-lg text-zinc-300 max-w-xl leading-relaxed">
47
- Standardized assessment workflow, objective criteria tracking, and multi-district reporting on a unified surface.
48
- </p>
49
-
50
- <!-- Factual Key Indicators (Plain typographic numbers, not floating cards) -->
51
- <div class="pt-6 border-t border-zinc-800 flex flex-wrap gap-8 text-sm">
52
- <div>
53
- <span class="block text-2xl font-bold font-mono text-white tabular-nums">12</span>
54
- <span class="text-zinc-400">Core Categories</span>
55
- </div>
56
- <div>
57
- <span class="block text-2xl font-bold font-mono text-white tabular-nums">148</span>
58
- <span class="text-zinc-400">Verified Checkpoints</span>
59
- </div>
60
- <div>
61
- <span class="block text-2xl font-bold font-mono text-white tabular-nums">99.8%</span>
62
- <span class="text-zinc-400">On-Time Submissions</span>
63
- </div>
64
- </div>
65
- </div>
66
-
67
- <!-- Right: Single Functional Action Surface (5 cols) -->
68
- <div class="lg:col-span-5">
69
- <div class="bg-white text-zinc-900 rounded-xl p-7 shadow-xl space-y-5">
70
- <div class="border-b border-zinc-200 pb-4">
71
- <h2 class="text-lg font-bold text-zinc-900">District Access</h2>
72
- <p class="text-xs text-zinc-500 mt-1">Select an active region to inspect accreditation status</p>
73
- </div>
74
-
75
- <div class="space-y-3.5">
76
- <div>
77
- <label class="block text-xs font-semibold text-zinc-700 mb-1.5">Region</label>
78
- <select class="w-full text-sm rounded-lg border border-zinc-300 bg-zinc-50 px-3 py-2 text-zinc-800 focus:outline-none focus:ring-2 focus:ring-zinc-900">
79
- <option>Region North (Sector A)</option>
80
- <option>Region Central (Sector B)</option>
81
- <option>Region South (Sector C)</option>
82
- </select>
83
- </div>
84
- <div>
85
- <label class="block text-xs font-semibold text-zinc-700 mb-1.5">Organization Unit</label>
86
- <input type="text" placeholder="Search department or unit..." class="w-full text-sm rounded-lg border border-zinc-300 px-3 py-2 text-zinc-800 placeholder-zinc-400 focus:outline-none focus:ring-2 focus:ring-zinc-900" />
87
- </div>
88
- <button class="w-full bg-zinc-900 hover:bg-zinc-800 text-white font-medium text-sm rounded-lg py-2.5 transition-colors">
89
- Continue to Portal
90
- </button>
91
- </div>
92
- </div>
93
- </div>
94
-
95
- </div>
96
- </div>
97
- </section>
98
- ```
99
-
100
- ---
101
-
102
- ## Pattern 2: Progressive Category Explorer (Clean Overview + Focused Preview)
103
-
104
- *Use for: Large catalogs, complex instrument sets, curricula, feature breakdown.*
105
- *Key Traits: Prevents raw 100+ row table dumps on public pages while avoiding repetitive bento cards.*
106
-
107
- ```html
108
- <section class="py-16 lg:py-24 bg-zinc-50">
109
- <div class="max-w-6xl mx-auto px-6">
110
-
111
- <!-- Section Header (Clear and direct, no uppercase kicker) -->
112
- <div class="max-w-2xl mb-12">
113
- <h2 class="text-3xl font-bold tracking-tight text-zinc-900">Evaluation Criteria</h2>
114
- <p class="text-sm text-zinc-600 mt-2">Select a operational domain to review requirements and compliance records.</p>
115
- </div>
116
-
117
- <!-- Category Tabs & Preview Canvas -->
118
- <div class="bg-white rounded-xl border border-zinc-200/80 shadow-sm overflow-hidden">
119
- <!-- Category Strip -->
120
- <div class="grid grid-cols-2 md:grid-cols-4 border-b border-zinc-200 divide-x divide-zinc-200 bg-zinc-100/50 text-center text-xs font-medium">
121
- <button class="py-3.5 px-4 bg-white text-zinc-900 font-semibold border-b-2 border-zinc-900">
122
- Governance (25%)
123
- </button>
124
- <button class="py-3.5 px-4 text-zinc-600 hover:text-zinc-900 transition-colors">
125
- Financial Controls (25%)
126
- </button>
127
- <button class="py-3.5 px-4 text-zinc-600 hover:text-zinc-900 transition-colors">
128
- Field Operations (30%)
129
- </button>
130
- <button class="py-3.5 px-4 text-zinc-600 hover:text-zinc-900 transition-colors">
131
- Reporting & Audit (20%)
132
- </button>
133
- </div>
134
-
135
- <!-- Preview Table for Selected Category -->
136
- <div class="p-6">
137
- <div class="flex items-center justify-between mb-4">
138
- <div class="text-sm font-semibold text-zinc-900">Governance Benchmarks (24 Items)</div>
139
- <span class="text-xs text-zinc-500 font-mono">Format: Signed PDF / Audit Log</span>
140
- </div>
141
-
142
- <table class="w-full text-left text-sm border-collapse">
143
- <thead>
144
- <tr class="border-b border-zinc-200 text-xs font-semibold text-zinc-500 uppercase">
145
- <th class="py-2.5 px-3 w-12 font-mono">No</th>
146
- <th class="py-2.5 px-4">Performance Indicator</th>
147
- <th class="py-2.5 px-4">Verification Artifact</th>
148
- <th class="py-2.5 px-3 w-20 text-right font-mono">Weight</th>
149
- </tr>
150
- </thead>
151
- <tbody class="divide-y divide-zinc-100 text-zinc-800">
152
- <tr>
153
- <td class="py-3 px-3 font-mono text-zinc-500">01</td>
154
- <td class="py-3 px-4 font-medium">Annual Board Review Minutes</td>
155
- <td class="py-3 px-4 text-zinc-600">Signed meeting resolution and verified attendance roll</td>
156
- <td class="py-3 px-3 text-right font-mono tabular-nums">5.0%</td>
157
- </tr>
158
- <tr>
159
- <td class="py-3 px-3 font-mono text-zinc-500">02</td>
160
- <td class="py-3 px-4 font-medium">Quarterly Budget Reconciliation</td>
161
- <td class="py-3 px-4 text-zinc-600">Reconciled bank statement and expenditure journal</td>
162
- <td class="py-3 px-3 text-right font-mono tabular-nums">4.5%</td>
163
- </tr>
164
- </tbody>
165
- </table>
166
- </div>
167
- </div>
168
-
169
- </div>
170
- </section>
171
- ```
172
-
173
- ---
174
-
175
- ## Pattern 3: Clean Human Directory (No Infinite Marquee, No 3-Level Card Nest)
176
-
177
- *Use for: Advisory boards, committees, team members, reviewers.*
178
- *Key Traits: Uses subtle natural spacing and typography instead of infinite marquee tickers or nested card boxes.*
179
-
180
- ```html
181
- <section class="py-16 lg:py-24 bg-white border-t border-zinc-200">
182
- <div class="max-w-6xl mx-auto px-6">
183
-
184
- <div class="max-w-2xl mb-12">
185
- <h2 class="text-3xl font-bold tracking-tight text-zinc-900">Review Committee</h2>
186
- <p class="text-sm text-zinc-600 mt-2">Accredited evaluators and audit leads for the current inspection cycle.</p>
187
- </div>
188
-
189
- <!-- Direct Grid: Unnested, clean borders or airy spacing -->
190
- <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
191
-
192
- <div class="space-y-3">
193
- <div class="flex items-center gap-4">
194
- <div class="w-12 h-12 rounded-lg bg-zinc-100 border border-zinc-200 flex items-center justify-center font-bold text-zinc-700">
195
- ER
196
- </div>
197
- <div>
198
- <h3 class="text-base font-bold text-zinc-900">Elena Rostova, Ph.D.</h3>
199
- <p class="text-xs text-zinc-500 font-medium">Lead Governance Auditor</p>
200
- </div>
201
- </div>
202
- <p class="text-xs text-zinc-600 leading-relaxed">
203
- Oversees statutory compliance, governance resolutions, and organizational constitution reviews.
204
- </p>
205
- </div>
206
-
207
- <div class="space-y-3">
208
- <div class="flex items-center gap-4">
209
- <div class="w-12 h-12 rounded-lg bg-zinc-100 border border-zinc-200 flex items-center justify-center font-bold text-zinc-700">
210
- MC
211
- </div>
212
- <div>
213
- <h3 class="text-base font-bold text-zinc-900">Marcus Chen, CPA</h3>
214
- <p class="text-xs text-zinc-500 font-medium">Senior Financial Evaluator</p>
215
- </div>
216
- </div>
217
- <p class="text-xs text-zinc-600 leading-relaxed">
218
- Verifies accounting balances, grant disbursements, and audit trails across regional chapters.
219
- </p>
220
- </div>
221
-
222
- </div>
223
- </div>
224
- </section>
225
- ```
226
-
227
- ---
228
-
229
- ## Pattern 4: Operational Workspace (High-Density Master-Detail for Authenticated Users)
230
-
231
- *Use for: Internal dashboard, audit workstation, evaluator screen.*
232
- *Key Traits: Sticky column headers, tabular figures, master-detail side rail, zero consumer fluff.*
233
-
234
- ```html
235
- <div class="min-h-dvh flex flex-col bg-zinc-100 text-zinc-900">
236
- <!-- Top Bar -->
237
- <header class="h-14 bg-white border-b border-zinc-200 px-6 flex items-center justify-between">
238
- <div class="flex items-center gap-3">
239
- <span class="font-bold text-sm">AUDIT DESK</span>
240
- <span class="text-zinc-300">/</span>
241
- <span class="text-xs text-zinc-600">District 04 (Central Sector)</span>
242
- </div>
243
- <div class="flex items-center gap-4 text-xs">
244
- <span class="text-zinc-500">Evaluator: Field Team 2</span>
245
- <button class="bg-zinc-900 text-white px-3 py-1.5 rounded-md font-medium hover:bg-zinc-800">
246
- Save Evaluation
247
- </button>
248
- </div>
249
- </header>
250
-
251
- <!-- Split View (Master list left, detail right) -->
252
- <div class="flex-1 flex overflow-hidden">
253
- <!-- Left Rail: Categories & Status (280px) -->
254
- <aside class="w-72 bg-white border-r border-zinc-200 p-4 space-y-2 overflow-y-auto">
255
- <div class="text-xs font-semibold text-zinc-500 px-2 uppercase tracking-wide">Audit Categories</div>
256
- <button class="w-full text-left px-3 py-2 rounded-lg bg-zinc-100 font-medium text-xs text-zinc-900 flex justify-between items-center">
257
- <span>Governance</span>
258
- <span class="text-emerald-700 font-mono">18/22</span>
259
- </button>
260
- <button class="w-full text-left px-3 py-2 rounded-lg hover:bg-zinc-50 text-xs text-zinc-600 flex justify-between items-center">
261
- <span>Field Operations</span>
262
- <span class="text-amber-700 font-mono">10/25</span>
263
- </button>
264
- </aside>
265
-
266
- <!-- Main Workspace: Dense Data Table with inline inspector -->
267
- <main class="flex-1 p-6 overflow-y-auto">
268
- <div class="bg-white rounded-lg border border-zinc-200 shadow-xs overflow-hidden">
269
- <table class="w-full text-left text-xs border-collapse">
270
- <thead class="bg-zinc-50 border-b border-zinc-200 text-zinc-600 font-semibold sticky top-0">
271
- <tr>
272
- <th class="py-2.5 px-3 w-10 font-mono">No</th>
273
- <th class="py-2.5 px-3">Audit Item</th>
274
- <th class="py-2.5 px-3">Submitted Evidence</th>
275
- <th class="py-2.5 px-3 w-28">Status</th>
276
- <th class="py-2.5 px-3 w-24 text-right">Action</th>
277
- </tr>
278
- </thead>
279
- <tbody class="divide-y divide-zinc-100 text-zinc-800">
280
- <tr>
281
- <td class="py-2.5 px-3 font-mono text-zinc-400">01</td>
282
- <td class="py-2.5 px-3 font-medium">Bylaw Resolution Filing</td>
283
- <td class="py-2.5 px-3 text-zinc-500">bylaw_resolution_2026.pdf (1.2 MB)</td>
284
- <td class="py-2.5 px-3">
285
- <span class="inline-flex items-center px-2 py-0.5 rounded text-[11px] font-medium bg-emerald-50 text-emerald-800 border border-emerald-200">
286
- Verified
287
- </span>
288
- </td>
289
- <td class="py-2.5 px-3 text-right">
290
- <button class="text-zinc-900 hover:underline font-medium">Inspect</button>
291
- </td>
292
- </tr>
293
- </tbody>
294
- </table>
295
- </div>
296
- </main>
297
- </div>
298
- </div>
299
- ```