# Design Guidance — brianparisien.dev
This file is public guidance for any agent or person generating or editing a page
on this site. It is prose, not code. The rules it names are enforced by a single
bounded stylesheet (`/app/globals.css`) that the browser loads and that you do
**not** need to read. Author semantic HTML, apply the class names listed here, and
the visual system resolves itself.
If you follow one instruction from this document, follow this: **the site exists
to show judgment, not to impress.** Every decoration spends credibility. Spend it
only on evidence.
---
## 1. Core purpose
The site helps Brian Parisien get hired, mainly as an AI Agent Manager (also AI
Project/Program Manager, AI Product Manager and AI Automation Specialist). It has a
Home page, one case study (Apex Climate Solutions, a simulated heating and cooling
business) and five linked project documents.
It serves two readers at once:
1. **A person deciding whether to interview Brian**: a hiring manager skimming for
judgment, a recruiter matching a role, or a technical reviewer checking claims.
2. **An AI tool reading the page text or `/llms.txt`** and repeating what it finds.
Vague or inconsistent wording gets repeated vaguely.
A page that reads well as plain text in a terminal serves both.
---
## 2. Design philosophy
Plain, calm, specific and evidence-led. The look is a well-set document: warm
off-white paper, near-black ink, Tenor Sans headings, one burgundy accent, and blue for links only.
The site is for hiring, not client work. No page offers services, quotes prices or
asks for a project. There is no contact form; the footer carries Resume, LinkedIn,
Email and "Panama City, UTC−5".
---
## 3. Voice
Site pages speak as Brian in the first person. Linked project documents describe
the system and never name him ("the project owner" where someone must be named).
The full voice rules, terms and the list of what never ships live in the project
style guide; they apply to anything visible on the site.
- Specific over impressive. Label every number with what it is (test score,
estimate, modeled, measured).
- No hype words and no exclamation marks.
- US English. Dates as "October 28, 2026" in sentences, "Oct 28, 2026" in tables.
- Text in square brackets, such as `[runtime]`, is a known unknown and shows as a
visible placeholder until it is filled in.
---
## 4. Typography
Three faces, loaded with `next/font/google`:
- **IBM Plex Sans**: body text at 17px, line height 1.6.
- **Tenor Sans, regular (400)**: all headings and the large numbers. It has one weight, so headings are never bolded.
- **The wordmark**: "Brian Parisien" in the header is a drawn logo (SVG) with three accent-colored dots over the "i"s.
- **IBM Plex Mono, weight 500**: small uppercase labels at 12px with 0.08em letter
spacing, and placeholders. Never for emphasis.
Use the published type roles (`bp-title`, `bp-lede`, `bp-heading`, `bp-label`).
Do not introduce arbitrary sizes or weights.
- **Section titles are one size**: 28px on desktop, 24px on mobile. Only the page
headline (`bp-title`) is larger.
- One `
` per page. Headings in order, never skipped for visual effect.
- Rhythm comes from relationships: heading-to-body is close, section-to-section is
clearly larger.
---
## 5. Color and surface
The site always opens in the light theme, whatever the visitor's system setting.
A small light/dark switch in the header (a keyboard-accessible button) turns the
dark theme on and remembers the choice in the browser. The dark tokens below
apply only when the visitor has chosen dark. Without JavaScript the site stays
light and the switch is hidden.
| Role | Light | Dark |
| --- | --- | --- |
| Page | `#FBFAF7` | `#161513` |
| Ink (text) | `#1D1C1A` | `#ECE9E2` |
| Muted text | `#55524C` | `#B3AEA4` |
| Accent (labels, small marks, focus rings, hover states) | `#7B1E3A` | `#E6A3B6` |
| Links (hyperlinks only) | `#1D4E9E` | `#93B8F6` |
| Hairlines | `#E2DED6` | `#33302B` |
| Inverse band, background (Home only) | `#1D1C1A` | `#F2EFE8` |
| Inverse band, text | `#ECE9E2` | `#1D1C1A` |
| Hand-off to a person (amber) | `#A86400` | `#E2A24A` |
| Placeholder mark (yellow) | `#FFF1BF` on `#4F3D00` | `#4A3B0A` on `#FBE7A0` |
- Amber marks a step where a person decides. Purple (`--ai-line`) marks an AI step
and gray (`--rule-line`) a fixed-rule step, in diagrams only.
- Color is never the only signal. Pair it with a label, shape or underline.
- No cards around everything. Use whitespace and a hairline to separate. Reach for
a bordered container only when content is a distinct object (a table, a figure,
a callout, a role card).
- One flat inverse band is allowed on Home: the case study section and the footer are
dark in the light theme and light in the dark theme, edge to edge. Accent, link
and text colors switch with the band (see `--inv-*` in the stylesheet).
- Brand marks: the "Brian Parisien" wordmark (header and resume), the "B" monogram
favicon, and the stacked Apex logo (normal on light surfaces, reversed on dark
ones; the Home case study band and the case study headline). Do not redraw or
recolor them.
- Headings, buttons and menu labels use sentence case (capitalize the first word and names only). Role
titles and proper names keep their capitals. One dash style in titles: the long dash with spaces.
- The methodology page is named "How I build automation" (page title, left menu and Home section). The header link is the short form, "How I build". The page is a general method, not a project write-up, so it names no project.
- The demo video is not on the site yet. Its button, video box and menu link are commented out in the code
(marked HIDDEN). Restore them, with the runtime, only when the video exists.
- Home: the case study band is a four-column grid (heading column, then the content across three columns:
intro, a four-figure strip, three component cards). The About section uses the same columns (heading,
text across two, illustrated portrait in the fourth, light or dark version by theme).
- Case study page (wide screens): a three-column content area. The introduction runs across two columns
with the Apex logo and the results in the third; everything below spans all three. The logo is aligned
to the headline top and the date line bottom, and the rule above the first result lines up with the
note box. Break it shows the failure-route diagram and the alert screenshot as two equal boxes.
- Hard reject: gradients, glows, textures, grid or dot backgrounds, glass or blur
effects, drop shadows for depth.
---
### Diagram key
One key for every diagram on the site (case study and documents), so a color means the same thing everywhere. A diagram's legend lists only the keys it uses, and uses the wording below.
| Meaning | Legend wording | Color |
| --- | --- | --- |
| A step that follows fixed rules | Fixed rule | Gray (`--rule-fill`, `--rule-line`) |
| A step that calls an AI model | AI call | Purple (`--ai-fill`, `--ai-line`) |
| A step where a person decides | Person | Amber (`--person-fill`, `--person-line`) |
| A hand-off from an AI call to a person | Hand-off to a person | Thick amber arrow |
| A database or other store of records | Store | Green (`--store-fill`, `--store-line`) |
| A Slack channel or an outside input | Slack or input | Red-orange (`--channel-fill`, `--channel-line`) with a thick left edge |
| A failure route | Failure route | Dashed red arrow (`--fail`) |
Color is never the only signal: every box carries its label, the legend names each color in words, and Slack or input boxes also carry a thick left edge so they are not mistaken for people (amber).
## 6. Evidence
- Put units, time periods and populations next to the number they qualify.
- Diagrams are inline SVG built in code, never screenshots. Each has its own
legend listing only the keys it uses, a caption and alt text.
- Tables are semantic (`
` inside `bp-table-wrap`): text columns left,
numeric columns right, one header row.
- Use a chart for a relationship, a table for a precise lookup. If in doubt, table.
---
## 7. Motion
Default to stillness. The only acceptable motion is a sub-150ms state change on
focus or hover. Never animate content in on scroll.
---
## 8. The bounded class vocabulary
Use these class names. Do not invent synonyms. If you need something not listed
here, use a plain semantic element with no class and let the stylesheet's element
defaults apply.
**Layout**
| Class | Use |
| --- | --- |
| `bp-page` | Root wrapper, the first child of ``. |
| `bp-shell` | Centered column with the page's max width and gutters. `data-width="wide"` gives the header and footer width. |
| `bp-header` | Site header: wordmark link and primary nav. |
| `bp-footer` | Site footer: Resume, LinkedIn, Email, place. |
| `bp-nav` | The primary navigation `