|
1 | 1 | --- |
2 | | -name: Foreman |
3 | | -description: An always-on AI co-maintainer for your GitHub repositories. |
| 2 | +name: Night Brownie |
| 3 | +description: A stealthy, always-on AI co-maintainer for your GitHub repositories. |
4 | 4 | colors: |
5 | | - blueprint-steel: "#43527A" |
6 | | - pre-dawn-navy: "#172A54" |
7 | | - safety-tape-pale: "#FDF396" |
8 | | - site-signal-amber: "#F7B526" |
9 | | - construction-orange: "#FE6400" |
| 5 | + midnight-indigo: "#1A2136" |
| 6 | + twilight-purple: "#362A54" |
| 7 | + biolume-cyan: "#7EE2F5" |
| 8 | + moonlit-silver: "#D4D9EB" |
| 9 | + velvet-black: "#0A0D14" |
10 | 10 | typography: |
11 | 11 | headline: |
12 | 12 | fontFamily: "Public Sans, system-ui, -apple-system, sans-serif" |
@@ -41,234 +41,122 @@ components: |
41 | 41 | rounded: "{rounded.sm}" |
42 | 42 | padding: "{spacing.md}" |
43 | 43 | card-header: |
44 | | - backgroundColor: "{colors.blueprint-steel}" |
| 44 | + backgroundColor: "{colors.midnight-indigo}" |
45 | 45 | textColor: "#ffffff" |
46 | 46 | padding: "16px 16px 24px" |
47 | 47 | tag: |
48 | | - backgroundColor: "rgba(0, 0, 0, 0.08)" |
49 | | - textColor: "{colors.pre-dawn-navy}" |
| 48 | + backgroundColor: "rgba(26, 33, 54, 0.08)" |
| 49 | + textColor: "{colors.midnight-indigo}" |
50 | 50 | rounded: "{rounded.pill}" |
51 | 51 | padding: "2px 8px" |
52 | 52 | doc-label: |
53 | | - backgroundColor: "{colors.blueprint-steel}" |
| 53 | + backgroundColor: "{colors.midnight-indigo}" |
54 | 54 | textColor: "#ffffff" |
55 | 55 | rounded: "{rounded.pill}" |
56 | 56 | padding: "0 5px" |
57 | 57 | --- |
58 | 58 |
|
59 | | -# Design System: Foreman |
| 59 | +# Design System: Night Brownie |
60 | 60 |
|
61 | 61 | ## 1. Overview |
62 | 62 |
|
63 | | -### Creative North Star: "The Infrastructure Manual" |
64 | | - |
65 | | -This is documentation built the way a night brownie runs a job site: precise, no wasted motion, |
66 | | -and trustworthy on day one and day five hundred. |
67 | | -The visual system earns credibility through restraint. |
68 | | -A developer who lands on these docs is skeptical by default — |
69 | | -they've been burned by tools with slick marketing that delivered nothing. |
70 | | -Foreman's design answers that skepticism by refusing to perform. |
71 | | -No animated hero numbers, no gradient blobs, no "10x your workflow" copy. |
72 | | -Just dense, correct, structured information that says: this was built by people who use tools like this. |
73 | | - |
74 | | -The reference is the kind of documentation engineers save as a bookmark and actually return to: |
75 | | -Docker Compose reference, the GNU Make manual, Stripe's API docs. |
76 | | -These are trusted not because they look expensive, but because they have exactly what you need and nothing you don't. |
77 | | -Color is used for orientation, not decoration. |
78 | | -Typography is functional, not expressive. |
79 | | -Every component earns its place by doing a job. |
80 | | - |
81 | | -This system is explicitly not an AI startup landing page. |
82 | | -No glassmorphism, no hero metrics, no gradient text, no friendly onboarding flows. |
83 | | -The people who need Foreman already know they need it. |
84 | | -The design's job is to get out of the way and prove the tool with information. |
| 63 | +### Creative North Star: "The Midnight Helper" |
| 64 | + |
| 65 | +This system is built for the quiet efficiency of a helper who works while the world sleeps. |
| 66 | +It values stealth, competence, and clarity. |
| 67 | +The visual system earns credibility through calm and focus. |
| 68 | +A developer who lands here is looking for a tool that solves problems without creating noise. |
| 69 | +Night Brownie's design reflects this by being unobtrusive, dense with information, |
| 70 | +and oriented toward nighttime productivity. |
| 71 | + |
| 72 | +The reference is a well-organized toolkit or a quiet library: Everything has its place, the lighting is focused, |
| 73 | +and the atmosphere is one of productive calm. |
| 74 | +Color is used to highlight paths in the dark (biolume cyan), not for decoration. |
| 75 | +Typography is precise and functional. |
| 76 | +Every component exists to serve the primary goal: making repository maintenance invisible and effortless. |
85 | 77 |
|
86 | 78 | ### Key Characteristics |
87 | 79 |
|
88 | | -- Flat surfaces: depth through tonal color difference and 1px borders, never shadows |
89 | | -- Construction-site palette: anchored in physical-world signaling colors |
90 | | -- Weight-driven type hierarchy: scale and weight contrast, no decorative typefaces |
91 | | -- Components that document, not decorate |
| 80 | +- **Midnight-First**: Optimized for dark environments and focused work. |
| 81 | +- **Tonal Depth**: Using subtle shifts in dark tones rather than shadows to define structure. |
| 82 | +- **Fixed Points of Light**: Using high-contrast cyan accents sparingly for navigation and primary actions. |
| 83 | +- **Dense Utility**: Information-rich components that stay out of the way until needed. |
92 | 84 |
|
93 | | -## 2. Colors: The Worksite Palette |
| 85 | +## 2. Colors: The Midnight Palette |
94 | 86 |
|
95 | | -The palette draws from a physical job site. |
96 | | -Deep navy frames the structure, amber signals waypoints, and one vivid orange marks action — |
97 | | -the way a hard hat orange does. |
| 87 | +The palette is anchored in the deep tones of night, with highlights that cut through the dark like starlight. |
98 | 88 |
|
99 | 89 | ### Primary |
100 | 90 |
|
101 | | -- **Blueprint Steel** (`oklch(42% 0.065 258)` / `--blueprint-steel`): The workhorse color. |
102 | | - Used for the navigation header, card headers, active states, and links. |
103 | | - Medium slate-blue — calm, authoritative, legible against white. |
104 | | - Not vibrant enough to feel "AI startup blue." |
105 | | -- **Pre-Dawn Navy** (`oklch(23% 0.085 263)` / `--pre-dawn-navy`): The darkest brand tone. |
106 | | - Used for deep backgrounds, heavy text contexts, and the logo mark. |
107 | | - Its intensity signals depth and seriousness. |
| 91 | +- **Midnight Indigo** (`oklch(25% 0.08 260)` / `--midnight-indigo`): The structural anchor. |
| 92 | + Used for headers, active navigation, and primary branding. |
| 93 | + A deep, trustworthy indigo that signals depth and stability. |
| 94 | +- **Biolume Cyan** (`oklch(80% 0.12 200)` / `--biolume-cyan`): The guiding light. |
| 95 | + Reserved for primary CTAs and critical orientation points. |
| 96 | + Its vibrant, mascot-inspired glow makes it instantly recognizable against the dark backgrounds. |
108 | 97 |
|
109 | 98 | ### Secondary |
110 | 99 |
|
111 | | -- **Site Signal Amber** (`oklch(77% 0.17 80)` / `--site-signal-amber`): The accent. |
112 | | - Used for interactive highlights, hover states, and emphasis marks. |
113 | | - Warm and high-contrast against navy — the equivalent of a fluorescent safety marker. |
114 | | -- **Construction Orange** (`oklch(63% 0.22 42)` / `--construction-orange`): The logo's action color. |
115 | | - Reserved for primary CTAs and the most important interactive actions on a page. |
116 | | - Use sparingly: its rarity is the point. |
117 | | - |
118 | | -### Tertiary |
119 | | - |
120 | | -- **Safety Tape Pale** (`oklch(95% 0.14 103)` / `--safety-tape-pale`): A pale, almost-neutral lemon-yellow. |
121 | | - Used at very low opacity as a surface tint (sidebar background wash). |
122 | | - Never as a foreground or text color — it reads as highlight, not content. |
| 100 | +- **Biolume Violet** (`oklch(70% 0.15 300)` / `--biolume-violet`): The character tone. |
| 101 | + Used for secondary interaction accents and brand-identifying decorative elements. |
| 102 | +- **Moonlit Silver** (`oklch(80% 0.02 260)` / `--moonlit-silver`): The accent neutral. |
| 103 | + Used for secondary borders, meta-text, and subtle interactive states. |
| 104 | +- **Starlight White** (`oklch(96% 0.02 200)` / `--starlight-white`): The sparkle of code. |
| 105 | + Used for tiny accents, particles, and high-contrast text elements that need to feel radiant. |
| 106 | +- **Twilight Purple** (`oklch(30% 0.09 295)` / `--twilight-purple`): The companion tone. |
| 107 | + Used for secondary structural elements and decorative accents that need to stay within the nocturnal vibe. |
123 | 108 |
|
124 | 109 | ### Neutral |
125 | 110 |
|
126 | | -- **Near-Black** (`oklch(15% 0.015 258)` / `--near-black`): The default body text color. |
127 | | - Set as `--md-default-fg-color` override. |
128 | | - Tinted toward the brand hue — pure `#000000` is forbidden. |
129 | | -- **Surface whites and off-whites**: Zensical theme defaults. |
130 | | - Card bodies are white; the sidebar receives the Safety Tape Pale wash at 7% opacity |
131 | | - (`--safety-tape-pale--lightest`). |
| 111 | +- **Velvet Black** (`oklch(12% 0.01 260)` / `--velvet-black`): The default deep background. |
| 112 | + A rich, dark surface that is easier on the eyes than pure black. |
| 113 | +- **Moonlit White** (`oklch(95% 0.01 260)` / `--moonlit-white`): The default text color. |
| 114 | + An off-white tinted toward the brand indigo to reduce harsh contrast. |
132 | 115 |
|
133 | 116 | ### Named Rules |
134 | 117 |
|
135 | | -**The One Orange Rule.** |
136 | | -Construction Orange appears on one primary action per screen. |
137 | | -Its rarity is the point. |
138 | | -When everything is orange, nothing is urgent. |
| 118 | +**The Biolume Rule.** |
| 119 | +Biolume Cyan should appear sparingly—ideally only once or twice on a screen. |
| 120 | +Like the mascot's energy, its value comes from its isolation and guidance. |
139 | 121 |
|
140 | | -**The Blue-Not-Indigo Correction.** |
141 | | -The Material theme's `--md-primary-fg-color--light` (`#ECB7B7`) |
142 | | -and `--md-primary-fg-color--dark` (`#90030C`) are off-brand carryover defaults. |
143 | | -Replace both with tints and shades derived from Blueprint Steel, not from unrelated red/pink values. |
| 122 | +**Tonal Layering.** |
| 123 | +Depth is created by moving between Velvet Black, Midnight Indigo, and Twilight Purple. |
| 124 | +Avoid box-shadows; use 1px borders in Moonlit Silver or tonal shifts to define boundaries. |
144 | 125 |
|
145 | 126 | ## 3. Typography |
146 | 127 |
|
147 | | -**Body Font:** Public Sans (Google Fonts, via `[project.theme.font] text = "Public Sans"` in `zensical.toml`) with |
148 | | -`system-ui, -apple-system, sans-serif` fallback. |
149 | | -**Label/Mono Font:** System monospace stack for code samples. |
| 128 | +**Body Font:** Public Sans. |
| 129 | +**Label/Mono Font:** System monospace. |
150 | 130 |
|
151 | | -**Character:** A single neutral sans-serif family. |
152 | | -No display font. |
153 | | -The decision is deliberate: Foreman's documentation is a reference, not a brand expression. |
154 | | -Typography serves legibility and hierarchy — the words carry the voice, not the typeface. |
| 131 | +Typography is tool-like. |
| 132 | +It doesn't perform; it informs. |
155 | 133 |
|
156 | 134 | ### Hierarchy |
157 | 135 |
|
158 | | -- **Headline** (700 weight, 1.5rem, lh 1.334): Section and page titles. |
159 | | - The primary visual anchor on any doc page. |
160 | | -- **Body** (400 weight, 1rem, lh 1.6): All prose content. |
161 | | - Max line length 70ch. |
162 | | - Wider than that and the reader loses the line. |
163 | | -- **Label** (500 weight, 0.8125rem, lh 1.75, ls 0.029em): Card subtitles, meta text, tag labels, |
164 | | - navigation secondary text. |
165 | | - Slightly tracked for legibility at small size. |
166 | | -- **Code** (system-ui-monospace, 0.875rem): Inline code and code blocks. |
167 | | - Distinguishable from prose at a glance. |
| 136 | +- **Headline** (700 weight, 1.5rem, lh 1.334): Clear anchors. |
| 137 | +- **Body** (400 weight, 1rem, lh 1.6): Dense but legible prose. |
| 138 | +- **Label** (500 weight, 0.8125rem, lh 1.75): Meta-information and small UI elements. |
168 | 139 |
|
169 | | -### Named Rules |
| 140 | +## 4. Elevation |
170 | 141 |
|
171 | | -**The Single-Family Rule.** One typeface. |
172 | | -Different weights and sizes, not different families. |
173 | | -Mixing a display serif into developer docs reads as a design decision made by someone who doesn't use the docs. |
| 142 | +The system is flat and layered. |
| 143 | +Depth is expressed through: |
174 | 144 |
|
175 | | -## 4. Elevation |
| 145 | +1. **Background Contrast**: Darker surfaces are "further away"; lighter surfaces are "closer". |
| 146 | +2. **Borders**: 1px borders in `oklch` with low opacity for subtle definition. |
176 | 147 |
|
177 | | -This system is flat by default. |
178 | | -No `box-shadow` except browser-native focus rings (which must never be removed). |
179 | | -Depth is expressed through two mechanisms only: |
| 148 | +## 5. Components |
180 | 149 |
|
181 | | -1. **Tonal layering**: a surface that needs separation gets a different background color — |
182 | | - typically the Safety Tape Pale wash at 4–8% opacity, or a shift from white to `--md-default-bg-color--light`. |
183 | | -2. **1px borders**: when tonal difference alone isn't enough to separate an element, |
184 | | - a single 1px border in a muted tone provides the edge. |
185 | | - Use `rgba(0, 0, 0, 0.12)` or a Blueprint Steel tint at 20% opacity. |
| 150 | +### Feature Cards |
186 | 151 |
|
187 | | -Cards do not use Material's three-layer `box-shadow`. |
188 | | -Use the `--card-border` token: `1px solid oklch(42% 0.065 258 / 20%)`. |
| 152 | +Flat, bordered cards with a tonal header (Midnight Indigo). |
189 | 153 |
|
190 | | -**The Flat-First Rule.** |
191 | | -If you're reaching for `box-shadow`, try a border or background-color shift first. |
192 | | -Shadows communicate that an element is physically lifted — which implies interactivity or importance. |
193 | | -Use that signal only when it's true. |
| 154 | +### Status Tags |
194 | 155 |
|
195 | | -## 5. Components |
| 156 | +Pill-shaped, using low-opacity Midnight Indigo backgrounds with darker text for readability on light surfaces, |
| 157 | +or reversed for dark. |
| 158 | + |
| 159 | +### Action Buttons |
196 | 160 |
|
197 | | -### Navigation |
198 | | - |
199 | | -The Material header carries Blueprint Steel (`#43527A`) as its background. |
200 | | -Navigation links are white at rest, Site Signal Amber on hover and active state. |
201 | | -No underlines on hover — the color change is sufficient signal. |
202 | | -The sidebar receives the Safety Tape Pale wash at 7% opacity, |
203 | | -giving it a distinct but subtle identity without needing a border. |
204 | | - |
205 | | -### Cards |
206 | | - |
207 | | -- **Corner Style:** Gently rounded (4px radius — `{rounded.sm}`) |
208 | | -- **Background:** White body; Blueprint Steel header |
209 | | -- **Shadow Strategy:** None. |
210 | | - A single `1px solid rgba(67, 82, 122, 0.2)` border replaces the Material box-shadow. |
211 | | -- **Header Padding:** 16px 16px 24px (extra bottom space for the header-to-content transition) |
212 | | -- **Content Padding:** 16px on all sides |
213 | | -- **Card Header Title:** 700 weight, 1.14em — the primary information landmark in the card |
214 | | - |
215 | | -### Tags / Chips |
216 | | - |
217 | | -- **Style:** Pill shape (`{rounded.pill}`), muted background (`rgba(0,0,0,0.08)`), Pre-Dawn Navy text |
218 | | -- **Size:** 24px height, `{spacing.xs} {spacing.sm}` padding, label-weight type |
219 | | -- **Usage:** Read-only descriptors only. |
220 | | - Not interactive unless the design explicitly requires it. |
221 | | - Interactive tags get a Blueprint Steel border. |
222 | | - |
223 | | -### API Doc Labels |
224 | | - |
225 | | -- **Style:** Pill shape (`{rounded.pill}`), Blueprint Steel background, white text |
226 | | -- **Variants:** `private` (muted red), `property` (muted green), `read-only` (muted yellow). |
227 | | - Exact colors defined in `extra.css`. |
228 | | -- **Size:** Small (fits inline with body text). |
229 | | - Label-weight type, no letter-spacing. |
230 | | - |
231 | | -### Navigation (Sidebar) |
232 | | - |
233 | | -- **Default state:** Body text weight, no background |
234 | | -- **Active/current state:** Blueprint Steel text, 500 weight — no left-border accent stripe |
235 | | -- **Hover:** Site Signal Amber text |
236 | | - |
237 | | -**The No-Stripe Rule.** |
238 | | -No `border-left` accent stripe on sidebar items, list items, or callouts. |
239 | | -Ever. |
240 | | -A colored left border is decorative affectation. |
241 | | -Use background tint or text color for active state. |
242 | | - |
243 | | -## 6. Do's and Don'ts |
244 | | - |
245 | | -### Do |
246 | | - |
247 | | -- **Do** use Blueprint Steel for primary navigation, card headers, and active states — it is the load-bearing color. |
248 | | -- **Do** express depth through tonal background shifts and 1px borders instead of `box-shadow`. |
249 | | -- **Do** cap body prose at 70ch line length for legibility. |
250 | | -- **Do** use Construction Orange for one primary action per page — its scarcity signals importance. |
251 | | -- **Do** use Site Signal Amber for hover and active interactive states across the site. |
252 | | -- **Do** keep the sidebar tinted with Safety Tape Pale at 7% opacity — |
253 | | - it visually anchors the navigation zone without adding weight. |
254 | | -- **Do** maintain a minimum 4.5:1 contrast ratio on all text (WCAG AA). |
255 | | - |
256 | | -### Don't |
257 | | - |
258 | | -- **Don't** use gradient text (`background-clip: text`). |
259 | | - Never intentional. |
260 | | - Use a solid color. |
261 | | -- **Don't** use glassmorphism: blur backgrounds, frosted cards, backdrop-filter as decoration. |
262 | | -- **Don't** use hero metrics: big number, small label, gradient accent. |
263 | | - This is an AI startup cliché and it's prohibited. |
264 | | -- **Don't** use animated counters, scroll-triggered number tickers, or decorative entrance animations. |
265 | | -- **Don't** use a `border-left` greater than 1px as a colored accent stripe on any element. |
266 | | -- **Don't** use gradient blob backgrounds, mesh gradients, or radial color washes behind content. |
267 | | -- **Don't** use `#000000` or `#ffffff` as literal color values. |
268 | | - Tint every neutral toward the brand hue. |
269 | | -- **Don't** add Material's three-layer `box-shadow` to new components. |
270 | | - The shadow says "lifted and interactive"; flat says "structural and trusted." |
271 | | -- **Don't** write hero copy that makes promises about productivity ("10x", "streamline", "supercharge"). |
272 | | - State what Foreman does, not what it will do for your feelings. |
273 | | -- **Don't** use the off-brand Material defaults `#ECB7B7` and `#90030C`. |
274 | | - Replace them with Blueprint Steel tints and shades. |
| 161 | +Primary actions use Biolume Cyan. |
| 162 | +Secondary actions use Moonlit Silver borders. |
0 commit comments