Mobile-first is the default approach. Base styles target mobile; enhancements are added at md: and above.
Use Tailwind CSS v4 default breakpoints, operating with two tiers as a rule.
Tier
Width
Tailwind prefix
Purpose
Mobile
< 768px
(none = base)
Single-column, stacked layout
Desktop
>= 768px
md:
Side-by-side, expanded layout
sm: / lg: / xl: / 2xl: should be used only as exceptions. Add a comment explaining the reason when used.
Maximum content width is max-w-4xl (896px), applied consistently across all pages.
Horizontal padding uses px-6 (24px) as the baseline.
Navigation
Tier
Behavior
Mobile
Hamburger toggle to show/hide navigation
Desktop
Persistent horizontal navigation bar
Typography scale
Headings use mobile sizes as the base and scale up by one step at md:.
Element
Mobile (base)
Desktop (md:)
Page title (h1)
text-3xl
md:text-4xl
Section heading (h2)
text-2xl
md:text-3xl
Sub-heading (h3)
text-xl
md:text-2xl
List heading
text-lg
md:text-xl
Body text
text-base
No change
Layout patterns
Pattern
Mobile
Desktop
Card list
Single-column stack
Single-column stack (sufficient within max-w-4xl)
Filter bar
Stacked flex-col
Horizontal md:flex-row
Footer
Stacked, centered
Horizontal md:flex-row md:justify-between
Header
Two rows + hamburger
Two rows + horizontal nav
Context
This site is a content-focused personal site (blog, tool catalog, ADR, About) where layouts rarely need to be complex. The existing implementation already uses only md:, effectively operating with two tiers. This implicit convention needed to be documented to maintain consistency in future development.
Rationale
Keep it simple: Two tiers are sufficient for a content-centric site. More breakpoints increase maintenance cost.
Consistency with existing code: The entire codebase already uses only md:, so no migration work is required.
Follow Tailwind defaults: Avoiding custom breakpoint definitions prevents drift from official documentation.
Mobile-first makes sense: Aligns with Google’s mobile-first indexing and prioritizes the mobile browsing experience.
Consequences
When building new components, complete the mobile layout first, then enhance with md:.
Using sm: / lg: etc. requires an explicit justification in the PR.
If content width beyond max-w-4xl is needed, a separate ADR should be created.
Typography scale changes should also be managed through ADRs.
hsb.horse