--- version: alpha name: "CarMax" website: "https://www.carmax.com" description: >- A used-vehicle retail marketplace whose marketing site was blocked by an Akamai CDN access-denial during extraction, returning only a plain error page with Times 16px and pure black (#000000) as the sole extractable CSS. The structural tokens in this file are built from that minimal extraction; the brand navy, amber, and full component palette from the live carmax.com storefront are documented as Known Gaps. CarMax is the largest used-car retailer in the United States, operating a search-first shopping interface with vehicle cards, pricing, and a vehicle-detail page that the extractor could not reach. seo: title: "CarMax Design System for React — bot-blocked extraction, structural tokens only, 12 components" metaDescription: "CarMax's design system as a DESIGN.md file — extraction was CDN-blocked; structural tokens from the error page plus Known Gaps documentation for the live storefront palette. For React, Next.js, and AI tools." highlights: - "CDN-blocked extraction — carmax.com returned an Akamai access-denial page; tokens are derived from the minimal error-page CSS and documented brand knowledge" - "Known Gaps flag — the brand navy, amber CTA, vehicle-card grid, search filter sidebar, and pricing display are not captured and are listed in Known Gaps" - "Minimal structural baseline — 3 color tokens (#000000 ink, white canvas, hairline), Times 16px/32px from the error page, 8px and 16px spacing from the extraction" - "Monochrome fallback pattern — button-primary uses ink-on-canvas with a hairline border, matching the no-brand-color pattern for extractions with no brand-layer color" - "Automotive retail archetype — vehicle-card grid, search/filter sidebar, and VDP (vehicle detail page) are the primary UI surfaces not represented here" tags: - "E-commerce & Retail" - "Automotive" lastUpdated: "2026-05-19" author: name: "Dov Azencot" url: "https://x.com/dovazencot" opening: | CarMax's website blocked the extractor at the CDN edge — Akamai returned an access-denial response before any marketing page rendered. The captured JSON reflects that blocked state: a single hex (#000000) at frequency 10, a Times serif at 16px and 32px from the browser's default error-page stylesheet, and an "Access Denied" h1 as the sole heading. No marketing chrome, no brand tokens, no component geometry reached the extractor. Where most bot-blocked sites at least serve a branded error page with a logo and palette, CarMax's Akamai configuration returns a plain text error with no CSS from the actual site. The result is a genuinely empty extraction from a site that publicly carries a recognizable brand identity — navy, amber, vehicle cards, a search-first layout — none of which is available in the token layer. The DESIGN.md file is structured around the minimal extractable data: 3 color tokens (ink black from the error page, implied white canvas, hairline as a single color for borders), 4 typography tokens from the Times error-page stylesheet and general rem-scale knowledge, a 0px radius matching the error page's geometry, and 12 component stubs that describe the structural roles on the actual CarMax storefront based on publicly observable UI patterns. The components use a monochrome ink-on-canvas pattern for all CTA surfaces, since no brand-layer color was confirmed by the extractor. Feed this file to Claude or Cursor for the structural skeleton — spacing rhythm, typography fallback scale, and component naming — and supplement with the brand palette documented in Known Gaps before building any CarMax-branded UI. The file is more useful as a structural contract (what components exist, what roles they fill) than as a token spec (what colors and fonts they use). Every token in the Known Gaps section is derivable from a re-extraction once the CDN block is resolved; the extraction command is `bun run design:extract https://www.carmax.com --slug carmax --force`. related: - href: "/design" title: "Browse all design systems" description: "The full directory of DESIGN.md files on shadcn.io, with live mockups for each." - href: "https://www.carmax.com" title: "CarMax — official site" description: "CarMax's public marketing site — the source of truth for the live tokens that a successful extraction would capture." - href: "https://github.com/google-labs-code/design.md" title: "The DESIGN.md specification" description: "Google Labs' open spec for machine-readable design system files — the format this page is built on." questions: - id: "extraction-status" title: "Why does this CarMax DESIGN.md have so few tokens?" answer: "CarMax's CDN (Akamai) blocked the headless browser extractor and returned an access-denial error page rather than the actual marketing site. The extraction captured only the error page's default browser stylesheet: Times serif at 16px and 32px, pure black (#000000) as the sole text and border color, and 8px / 16px spacing from the minimal error-page layout. No marketing chrome, no brand palette, and no component geometry from the actual carmax.com storefront was captured. The Known Gaps section documents what a successful extraction would add. To attempt a re-extraction: run `bun run design:extract https://www.carmax.com --slug carmax --force`." - id: "primary-color" title: "What is CarMax's primary brand color?" answer: "CarMax's publicly recognizable brand palette centers on a deep navy blue (used as the primary marketing surface and CTA fill) paired with an amber gold (used as a secondary accent on vehicle-price tags, promotional banners, and the brand's visual identity materials). Neither color was captured by the extractor — the CDN block returned an error page before any brand CSS was served. These colors are documented in Known Gaps. This DESIGN.md uses a monochrome ink-on-canvas fallback for all CTA surfaces, matching the extraction's single #000000 hex. A re-extraction of the live site would populate the brand palette." - id: "typography" title: "What typeface does CarMax use?" answer: "The extractor captured only Times New Roman at 16px (body) and 32px (h1) — the browser's default error-page stylesheet, not CarMax's brand typography. CarMax's live marketing site uses a custom typeface and/or a geometric sans for headings and body copy, but the specific font family names, weights, and tracking values were not captured. The typography tokens in this file use 'Times' as the fontFamily because that is the only font confirmed by the extraction; they should be replaced with the actual brand typeface once a re-extraction succeeds." - id: "vehicle-card" title: "What does CarMax's vehicle card grid look like?" answer: "The vehicle-card grid is the primary UI surface on carmax.com — a multi-column list of used vehicles showing a photo, year/make/model, mileage, price, and an Add to Favorites action. The grid was not captured by the extractor. Based on publicly observable CarMax UI patterns, each card uses a white surface with a subtle drop shadow or border, a rectangular or lightly rounded photo container at top, and a price displayed in a large sans-serif weight. The exact border-radius, shadow values, padding, and color tokens for this component are documented as a Known Gap and require a re-extraction to confirm." - id: "use-in-project" title: "Can I use this DESIGN.md to build an automotive retail or used-car marketplace UI?" answer: "Yes, with the caveat that this file documents the structural skeleton rather than the full brand palette. The component names and roles (vehicle-search-bar, vehicle-card, filter-sidebar, pricing-display, hero-heading) are accurate to the CarMax storefront archetype and useful for laying out the UI. The color tokens are monochrome placeholders derived from the error-page extraction. To build a CarMax-branded UI, supplement this file with the brand navy and amber from Known Gaps, replace the Times typography tokens with the actual brand typeface from a re-extraction, and add the vehicle-card component's radius and shadow values. As a structural contract for an automotive marketplace — search-first layout, vehicle grid, filter sidebar, VDP — the component set is complete." mockups: - "marketing-hero" - "media-grid" colors: ink: "#000000" canvas: "#ffffff" hairline: "#000000" typography: display-xl: fontFamily: "Times, \"Times New Roman\", serif" fontSize: 32px fontWeight: 700 lineHeight: "normal" letterSpacing: "normal" body-md: fontFamily: "Times, \"Times New Roman\", serif" fontSize: 16px fontWeight: 400 lineHeight: "normal" letterSpacing: "normal" label-md: fontFamily: "Times, \"Times New Roman\", serif" fontSize: 16px fontWeight: 400 lineHeight: "normal" letterSpacing: "normal" nav-link: fontFamily: "Times, \"Times New Roman\", serif" fontSize: 16px fontWeight: 400 lineHeight: "normal" letterSpacing: "normal" rounded: none: "0px" spacing: sm: "8px" base: "16px" md: "21px" components: button-primary: backgroundColor: "{colors.ink}" textColor: "{colors.canvas}" typography: "{typography.label-md}" rounded: "{rounded.none}" padding: "8px 16px" border: "0" button-secondary: backgroundColor: "{colors.canvas}" textColor: "{colors.ink}" typography: "{typography.label-md}" rounded: "{rounded.none}" padding: "8px 16px" borderColor: "{colors.hairline}" top-nav: backgroundColor: "{colors.canvas}" textColor: "{colors.ink}" typography: "{typography.nav-link}" rounded: "{rounded.none}" padding: "8px 16px" borderColor: "{colors.hairline}" nav-link: backgroundColor: "transparent" textColor: "{colors.ink}" typography: "{typography.nav-link}" padding: "8px 16px" hero-heading: backgroundColor: "transparent" textColor: "{colors.ink}" typography: "{typography.display-xl}" padding: "0px" body-paragraph: backgroundColor: "transparent" textColor: "{colors.ink}" typography: "{typography.body-md}" vehicle-search-bar: backgroundColor: "{colors.canvas}" textColor: "{colors.ink}" typography: "{typography.body-md}" rounded: "{rounded.none}" padding: "8px 16px" borderColor: "{colors.hairline}" vehicle-card: backgroundColor: "{colors.canvas}" textColor: "{colors.ink}" typography: "{typography.body-md}" rounded: "{rounded.none}" padding: "16px" borderColor: "{colors.hairline}" filter-sidebar: backgroundColor: "{colors.canvas}" textColor: "{colors.ink}" typography: "{typography.label-md}" rounded: "{rounded.none}" padding: "16px" borderColor: "{colors.hairline}" pricing-display: backgroundColor: "transparent" textColor: "{colors.ink}" typography: "{typography.display-xl}" padding: "0px" card: backgroundColor: "{colors.canvas}" textColor: "{colors.ink}" typography: "{typography.body-md}" rounded: "{rounded.none}" padding: "16px" borderColor: "{colors.hairline}" text-input: backgroundColor: "{colors.canvas}" textColor: "{colors.ink}" typography: "{typography.body-md}" rounded: "{rounded.none}" padding: "8px 16px" borderColor: "{colors.hairline}" --- ## Overview CarMax's extraction is a documented failure rather than a documented system. **Access-blocked baseline**: the headless extractor reached carmax.com, triggered Akamai's bot-detection, and received a plain access-denial page before any CarMax CSS was served. Every token in this file — the ink black, the Times fallback typography, the 8px spacing — comes from that error page's browser default stylesheet, not from CarMax's actual marketing system. Unlike monochrome fashion brands (Farfetch, ZARA) that genuinely run pure black on white, CarMax uses a recognizable navy-and-amber brand palette that was simply not reachable. The component structure reflects the actual CarMax storefront archetype, derived from publicly observable UI patterns. CarMax operates a search-first used-vehicle marketplace: a hero search bar above the fold, a vehicle-card grid as the primary content surface, a filter sidebar for refining by make/model/price/mileage, a pricing display showing the no-haggle price, and a vehicle-detail page (VDP) for individual listings. Where AutoTrader and Cars.com use a map-split layout for search results, CarMax defaults to a full-width card grid with the filter sidebar at left — a pattern closer to an e-commerce product grid than to a traditional automotive classifieds layout. **Key Characteristics:** - Extraction status: CDN-blocked. All color tokens are from the error-page default stylesheet, not from CarMax's brand system. - Single extracted color: #000000 at frequency 10 — 5 text, 5 border — from the Akamai error page. - Error-page typography: Times serif at 32px (h1) and 16px (body) — browser defaults, not brand fonts. - 0px corner radius from the error page; actual storefront radius values unknown. - 8px and 16px spacing from the error page layout — likely coincide with CarMax's actual 8px base spacing, but not confirmed. - Known brand palette (not captured): deep navy blue as primary surface and CTA, amber gold as secondary accent and pricing highlight. - Primary UI archetype: search-first vehicle marketplace with card grid, filter sidebar, and VDP. ## Colors ### Structural (error-page extraction only) - **Ink** (`#000000`): frequency 10. Used as text (5), border (5). The only hex captured by the extractor — from the Akamai error page, not from CarMax's CSS. Pure black at frequency 10 reflects the minimal browser-default error-page styling, not a deliberate brand token. - **Canvas** (`#ffffff`): the implied white background of the error page. Not declared explicitly in the captured CSS; inferred as the default. ### Not Captured — See Known Gaps The brand navy (CarMax's primary surface and CTA fill) and amber (secondary accent, pricing highlight, promotional elements) were not reached by the extractor. These are the load-bearing brand colors for any CarMax-branded UI and must be sourced separately. ## Typography ### Font Families The captured typography is entirely from the Akamai error page's browser default stylesheet — **Times New Roman** at 16px (body) and 32px (h1). This is not CarMax's brand typography. CarMax's actual marketing site uses a custom or licensed sans-serif typeface for headings and body copy; the specific font family name, weight ladder, and tracking values were not captured. The four typography tokens in this file use Times as the fontFamily because it is the only font confirmed by the extraction. Every token should be replaced with the actual brand typeface after a successful re-extraction. ### Hierarchy (error-page only) | Token | Size | Weight | Use | |---|---|---|---| | `{typography.display-xl}` | 32px | 700 | Error-page h1 ("Access Denied") — not a brand heading | | `{typography.body-md}` | 16px | 400 | Error-page body paragraph — browser default | | `{typography.label-md}` | 16px | 400 | Stub for label surfaces — needs re-extraction | | `{typography.nav-link}` | 16px | 400 | Stub for nav surfaces — needs re-extraction | ### Note on Font Substitutes Since no brand typeface was captured, no substitute recommendation is possible. After a successful extraction, this section should document the brand font family and recommend an open-source substitute at matching weights. ## Layout ### Spacing System - **Base unit:** 8px — from the error-page extraction (8px at frequency 1, 16px at frequency 2). Likely coincides with CarMax's actual 8px base spacing, but not confirmed. - **Tokens:** `{spacing.sm}` 8px · `{spacing.base}` 16px · `{spacing.md}` 21px. - **Actual storefront**: CarMax's search-first layout centers a large vehicle search bar above the fold, followed by a two-panel layout (filter sidebar at left, vehicle card grid at right). Section padding and grid gap values are not captured. ### Grid & Container The actual CarMax storefront uses a two-column layout for search results: a fixed-width filter sidebar (~280px) at left, and a fluid vehicle-card grid at right showing 3-4 columns at 1440px. The hero above the fold carries a search bar centered in a full-bleed banner. These grid values are documented as Known Gaps. ### Rhythm No marketing page rhythm was captured — the error page has no section bands, no editorial spacing. The spacing tokens (8px, 16px) are placeholders that should be confirmed against the actual storefront's spacing rhythm. ## Elevation No shadow values were captured from the error page. The actual CarMax vehicle card almost certainly carries a subtle box-shadow (automotive retail card grids consistently use shadow for card lift), but the exact shadow value — color, blur, spread — is not captured and is listed in Known Gaps. ## Shapes The extracted radius scale is 0px — from the error page, which has no styled surfaces. The actual CarMax storefront likely uses a modest radius scale (4–8px) on vehicle cards and CTA buttons, matching the automotive-retail convention. The 0px value here is an extraction artifact, not a brand decision. ## Components **`button-primary`** — Ink fill, white text, 0px radius, 8×16px padding. Monochrome fallback; the actual CTA fill is the brand navy (see Known Gaps). **`button-secondary`** — White canvas fill, ink text, 1px hairline border, 0px radius, 8×16px padding. Outlined secondary action. **`top-nav`** — White canvas surface, ink text, 1px bottom hairline. Houses the CarMax wordmark, primary nav links (Cars, Research, Sell/Trade, Financing, About Us), and utility actions (Saved Cars, Account, location selector). **`nav-link`** — Transparent background, ink text, 8×16px padding. Primary navigation links. **`hero-heading`** — Transparent background, ink text in the display-xl tier. The above-fold headline over the vehicle search bar. **`body-paragraph`** — Transparent background, ink text in body-md. Running paragraph text on editorial and informational pages. **`vehicle-search-bar`** — White canvas, ink text, 1px hairline border, 0px radius, 8×16px padding. The primary above-fold search input where shoppers enter make/model, ZIP code, or keyword. The most-used component on the marketing site. **`vehicle-card`** — White canvas, ink text in body-md, 1px hairline border, 0px radius, 16px internal padding. The repeating unit in the search-results grid — holds a vehicle photo, year/make/model headline, mileage, and the no-haggle price. **`filter-sidebar`** — White canvas, ink text in label-md, 1px right hairline border, 0px radius, 16px padding. The search filter panel at left on the results page — year range, make, model, price range, mileage, body style, color, location radius. **`pricing-display`** — Transparent background, ink text in display-xl. The no-haggle price display on vehicle cards and the VDP. CarMax's no-haggle pricing is a primary brand differentiator; the price is typically displayed at a large weight. **`card`** — White canvas, 1px hairline border, 0px radius, 16px padding. Generic content card for informational sections. **`text-input`** — White canvas, ink text in body-md, 1px hairline border, 0px radius, 8×16px padding. Form input field. ## Do's and Don'ts **Do** treat the vehicle-card as the primary UI component to build first. CarMax's product is a search grid of used vehicles — the vehicle card (photo, year/make/model, mileage, price) is what the system is built around. Get the card geometry right before worrying about the hero or footer. **Do** use the 8px base spacing unit as the grid module. The 8px value from the extraction is almost certainly the actual base — every automotive retail grid in the category (AutoTrader, Cars.com, Carvana) runs an 8px base, and 8px at frequency 1 from the error page is consistent with that. **Do** replace every typography token after a successful re-extraction. The Times fallback in this file is an extraction artifact; no production CarMax-branded UI should use Times New Roman. **Do** add the brand navy and amber from Known Gaps before building any CTA, pricing display, or promotional banner. The monochrome placeholders here are structurally correct but chromatically incorrect for a branded CarMax surface. **Don't** treat the 0px radius as a confirmed brand decision. The zero radius comes from the error page's browser defaults, not from CarMax's design system. The actual storefront likely uses 4–8px on vehicle cards and CTA buttons — confirm with a re-extraction before locking the radius scale. **Don't** omit the filter sidebar in any search-results implementation. The sidebar is load-bearing in the CarMax UX — shoppers navigate primarily through make/model/price/mileage filters, not through keyword search. Removing the sidebar removes the primary navigation mechanism. **Don't** replace the no-haggle price display with a range or negotiable-price pattern. CarMax's "no-haggle" pricing is a brand commitment that the pricing-display component must represent as a single, prominent number — not a range (AutoTrader convention) or a "call for price" placeholder. **Don't** use a map-split layout for search results. AutoTrader and Cars.com default to a map-split view (card list at left, map at right); CarMax defaults to a full-width card grid. The two patterns have different information hierarchies — using the wrong one would misrepresent how CarMax's users shop. ## Known Gaps - **CDN block — full re-extraction needed**: carmax.com blocked the extractor at the Akamai CDN layer. Run `bun run design:extract https://www.carmax.com --slug carmax --force` to attempt a re-extraction. If the block persists, try `--headed` to debug. - **Brand palette not captured**: CarMax's navy blue and amber gold — the two load-bearing brand colors — are absent from this file. These are the primary CTA fill (navy), the pricing-highlight and promotional accent (amber), and the nav-bar surface (navy). All color tokens in this file are structural placeholders. - **Brand typography not captured**: the actual CarMax typeface — a custom or licensed sans-serif — was not reached. All typography tokens in this file use Times New Roman from the browser default stylesheet and must be replaced. - **Vehicle card geometry**: border-radius, box-shadow, and internal padding of the vehicle card grid were not captured. These are the most implementation-relevant values for building a CarMax-style automotive retail UI. - **Search-bar component details**: the vehicle search input (ZIP code + make/model) includes custom autocomplete, location-detection, and a primary CTA button. The input geometry, button dimensions, and dropdown panel are not captured. - **VDP (vehicle detail page)**: the vehicle detail page — photo gallery, specifications table, pricing breakdown, CarMax guarantee block, financing call-to-action — is the primary conversion surface and was not captured. - **Mobile bottom navigation**: CarMax's mobile app and mobile web use a bottom-tab navigation bar; the web desktop top-nav and the mobile bottom-nav have different token requirements that are not represented here.