UI/UX Brief — DevFolio

Design principles, component behaviour, and user experience guidelines.

1. Design Philosophy

1.1 The site is the portfolio piece

A senior engineer's site is itself evidence. Bad spacing, inconsistent colour, and jumpy interactions undercut every claim in the copy. The design must read as deliberate — every choice traceable to a reason.

1.2 Principles

1.3 Visual language

1.4 Signature elements

Three deliberate choices give the site an identity that a template does not have:

1. Numbered section markers. Sections carry 01, 02, 03 in monospace beside the heading. Reads as an engineering document; costs nothing; impossible to mistake for a generic theme.
2. Terminal-tinted accent. The accent colour is drawn from the terminal-green/cyan family rather than the default brand-blue/violet. It signals "developer" without resorting to a fake terminal window.
3. Hairline grid reveals. The hero's fine grid pattern fades at the edges rather than ending abruptly, tying the hero to the page background instead of sitting on it as a rectangle.

2. Design Tokens

All tokens are declared once in resources/css/app.css under @theme (Tailwind v4 CSS-first configuration). A raw hex value in a template is a defect.

2.1 Colour

Semantic naming, not literal. Templates reference intent.

Contrast requirements. ink on canvas and accent on canvas must both clear 4.5:1. ink-muted on canvas must clear 4.5:1 for body-size text and may drop to 3:1 only for text ≥ 18.66 px bold or ≥ 24 px regular. These are verified at token-definition time, and the accent is the token most likely to fail — check it whenever it changes.

2.2 Typography

Rules.

• Body line-height 1.7; headings 1.15–1.25. Longer measure needs looser leading.
• Tracking tightens as size grows: -0.02em at h2, -0.03em at display.
• Reading measure capped at 68ch. Beyond that, the eye loses the line return.
• Numeric and technical strings use font-mono with font-variant-numeric: tabular-nums so figures align.
• Only two weights ship from the font loader (400, 500) plus a synthetic 600 where the browser provides it. A third web font weight is not worth the request.

2.3 Space, radius, elevation, motion

2.4 Dark mode

• Implemented as a token redefinition on .dark, declared alongside the light values so the two are read together.
• Flux owns the theme toggle and persistence via @fluxAppearance. Do not build a second toggle.
• Surfaces are lifted in dark mode (surface is lighter than canvas), the inverse of light mode. Shadows are ineffective on dark backgrounds — use a 1 px border on elevated layers instead.
• Images and inline SVG must not assume a light background: give diagrams explicit fill tokens rather than leaving them transparent.
• color-scheme: dark must be set so native form controls and scrollbars follow.

3. Layout System

3.1 Page shells

Revised — the original guidance was wrong. This table previously read "Existing starter-kit auth shells — reuse, do not rebuild" and "Existing starter-kit sidebar shell — extend the nav, do not replace the shell", justified on the grounds that the starter kit "already ships accessible auth and app shells with working theme handling".

That premise was false. All three starter-kit auth layouts (and the app shells) hardcoded class="dark" on <html>, overriding the visitor's theme choice. Someone who had selected the light theme was shown a dark sign-in page and then dropped into a light dashboard. The shells also rendered the framework's placeholder branding (a random Inspiring quote) rather than product copy, and only two of the three auth layouts were referenced at all — the third was dead weight with the same bug.

Rebuilding was therefore the correct call, not churn. The lesson worth recording: "the framework starter kit handles this" is an assumption that needs verifying, not a rationale. The app sidebar shell was worth extending rather than replacing; the auth shells were not.

Current auth layout structure. A two-column grid at lg and above — an editorial panel carrying the product's own copy, and the form column. Below lg the panel is dropped and the form is centred, because there is no room for a second column and no reason to make someone scroll past a manifesto to reach a password field.

The layout is theme-neutral: it reads the visitor's preference through @fluxAppearance like every other page, and hardcodes nothing. AuthLayoutTest asserts this, because it is a regression that renders a perfectly usable form and is therefore invisible without a test.

3.1.1 The dashboard sidebar

The sidebar is the densest navigational surface in the product, so its behaviour is specified rather than left to the implementation.

Structure. Three levels, and no deeper, because a fourth is where sidebars stop being readable:

Nothing is hidden behind a click. An earlier design gave multi-item groups a disclosure control that collapsed their links; it is gone, because a chevron between a section heading and three links is a navigation step with no information in it. A group that filters down to a single destination is still marked static in the data, and the navigation tests still pin the shape down.

Desktop — collapsible sidenav. The sidebar animates between a 264 px expanded state and a 68 px icon-only strip. The collapsed strip is built from the same navigation data, flattened; labels are replaced by icons but every link keeps a title and an aria-label, because an icon with no accessible name is unusable to a screen reader. The preference persists per account (df.sidenav-collapsed.{userId}), so two people sharing a browser do not fight over it. The toggle is an icon button in the brand row, beside the wordmark; at icon width the brand link yields the row to it, because a rail you cannot widen back is a trap.

Below lg — off-canvas drawer. The sidebar leaves the flow entirely and becomes a drawer over a backdrop. It is a role="dialog" aria-modal="true" and implements all three modal obligations: scroll lock on <html>, focus trapped within the drawer, and focus restored to the trigger on close. Escape closes it.

No group collapse state. With the disclosure gone there is nothing to persist per group: df.sidenav-collapsed.{userId} (the rail width) is the sidebar's only stored preference.

Active state is carried by three signals, never by colour alone: a signal-coloured left spine on the item, a filled background, and aria-current="page" in the markup.

Mobile drawer internals. The scrolling nav region is separate from the pinned footer, so the utility links never scroll out of reach. The collapse toggle is not in the footer at all — it is the icon button in the sidenav's brand row.

3.2 Public header behaviour

The header never hides on scroll-down. A portfolio reader frequently wants to jump to the blog mid-article, and a hiding header makes that a two-step interaction for no gain.

3.3 Responsive breakpoints

Rule. No horizontal overflow at any width from 360 px up. Verify with a long unbroken code line and a long unbroken URL — those are what actually break layouts.

4. Component Behaviour

Each component lists its states. Every interactive component must define all of: default, hover, focus-visible, active, disabled, and loading. A component with an undefined focus state is incomplete.

4.1 Buttons

States.

Sizing. sm 32 px, md 38 px, lg 44 px height. Icon-only buttons are square and must carry an accessible label via aria-label or a visually-hidden span.

4.2 Post card

┌─────────────────────────────────────────────┐
│ ┌─────────────────────────────────────────┐ │
│ │  category chip            reading time  │ │  ← meta row
│ └─────────────────────────────────────────┘ │
│                                             │
│  Post title that may wrap to two lines      │  ← h3, underline on hover
│                                             │
│  Excerpt, clamped to three lines...         │  ← ink-muted
│                                             │
│  #tag  #tag  #tag            12 Oct · 1.2k  │  ← footer row
└─────────────────────────────────────────────┘

Whole-card link with a nested link caveat. The card's primary link covers the card via a stretched pseudo-element; any inner link (category, tag) receives a higher z-index and position: relative so it stays independently clickable. Nested <a> elements are invalid HTML and are never emitted.

4.3 Tag pill / category chip

Active filters are visually unambiguous: filled background, accent border, and a leading check icon. Colour alone is not the signal.

4.4 Reading progress bar

4.5 Table of contents

Rule. The active-section indicator uses both colour and a border, because colour alone fails for readers with colour-vision deficiency.

4.6 Share bar

4.7 Comment item and form

4.8 Modal

Modal inventory.

4.9 Toast

Toasts appear bottom-right on desktop, bottom-centre on mobile, and are announced through an aria-live="polite" region. Max one toast at a time — a queue that stacks five toasts is noise.

4.10 Form fields

5. Page-Level UX Guidelines

5.1 Home

5.2 Blog index

• The featured post sits above the grid only when no filter is active. Showing a "featured" post that contradicts the active filter is confusing.
• Result count is always visible so the reader knows the scope of what they are looking at.
• Filters live in a sticky sub-bar on lg+ so they remain reachable while scrolling a long grid.
• Pagination preserves every active filter in its links.
• Scroll position returns to the top of the grid on page change; the rest of the page (header, filters) stays put.

5.3 Blog detail

• The article's first paragraph is the hook. No "Introduction" heading — it is filler.
• In-article links use the accent colour with an underline. Never rely on colour alone.
• Blockquotes get a 3 px accent left border and italic ink-muted text.
• Tables scroll horizontally within a wrapper; the page never scrolls sideways.
• Footnotes are out of scope for v1; inline asides use a bordered callout.
• The author card appears once, after the article, before comments. It is not repeated in the sidebar.

5.4 Dashboard

• Metric tiles are scannable at a glance: one number, one label, one deltas-free presentation. No chart junk.
• The post list is a table on lg+ and a stacked card list on smaller screens. Do not make a table horizontally scrollable on mobile if a card layout reads better.
• Status is conveyed by a chip with both text and colour.
• Destructive actions are visually separated from routine ones by a divider and are never the default-focused element.
• The pending-comment count is a persistent badge so moderation is never forgotten.

5.5 Post editor

• The preview is server-rendered by Livewire. Do not ship a second markdown parser to the browser — two implementations will diverge.
• The save-state indicator is always visible and never animates distractingly.
• Markdown shortcuts (bold, link, code fence, heading) are toolbar buttons that wrap the selection, so the author never has to remember syntax mid-thought.
• Autosave never publishes.
• Leaving with unsaved changes prompts for confirmation.
• Slug, when auto-derived, is shown as preview text and becomes editable on click. Do not silently change a published post's slug.

6. Accessibility Requirements

Target: WCAG 2.2 Level AA, verified with axe-core plus a manual keyboard pass.

7. Motion Guidelines

Rule. Skeleton shimmer is the only looping animation permitted anywhere, and it is disabled under reduced motion.

8. Content and Copy Guidelines

9. Quality Checklist

Before a UI change is considered complete:

• All six interaction states defined for every interactive element.
• Verified at 360 px, 768 px, 1024 px, 1440 px, 1920 px with no horizontal overflow.
• Verified in light and dark mode.
• Keyboard traversal complete in DOM order; focus never lost.
• axe-core reports zero violations.
• Contrast checked against the token table; accent is the usual failure point.
• prefers-reduced-motion verified by enabling the OS setting.
• No raw hex, px radius, or px shadow values in templates — tokens only.
• Loading, empty, error, and success states all render.
• Long content tested: a 40-character unbroken URL, a 200-character code line, a post title without spaces.
• Copy reviewed against the guidelines in §8.