---
title: "Read a company's design system"
method: GET
path: "/v1/web/styleguide"
tags: ["Brand"]
---

# Read a company's design system

`GET /v1/web/styleguide`

## Request

- Base URL: `https://api.hydrafetch.com`
- URL: `https://api.hydrafetch.com/v1/web/styleguide`
- Auth: API key in header `X-API-Key`

The colours, type scale, corner radius, buttons and component treatments a site actually paints, read from computed styles in a real browser, so a value defined through four layers of CSS variables comes back as the hex it resolved to. Colours are given by role (background, surface, text, accent) with contrast ratios, plus the dark theme when the site has one, so they drop into a theme without guesswork. Panels, the header bar, tabs and dark bands come back as values and as paste-ready CSS. A render every time, which is why it costs more than a brand lookup; cached for weeks after the first call unless you pass `maxAge`.

## Query parameters

- `domain` string
- `url` string
- `maxAge` number

## Response `200`

The design system.

- StyleguideResponseDto
  - `data` WebStyleguideDataDto, required
    - `domain` string, required
    - `page` string: The page that was read, when you asked for one with `url`.
    - `mode` 'light' | 'dark': Whether the page as first loaded is light or dark. `colors` describe this mode.
    - `dark` StyleguideDarkDto
      - `colors` StyleguideColorDto[], required
        - `hex` string, required
        - `name` string
        - `role` 'background' | 'surface' | 'text' | 'accent', required: Roles rather than a ranked list, so a colour drops straight into a theme instead of leaving you to guess which one is safe behind text.
      - `button` StyleguideDarkButtonDto
        - `background` string, required
        - `color` string
      - `contrast` StyleguideContrastDto
        - `textOnBackground` number: Contrast ratio of text against background.
        - `meetsAA` boolean: Whether that ratio clears WCAG AA.
        - `accentOnBackground` number
    - `components` StyleguideComponentsDto
      - `panel` StyleguidePanelDto
        - `border` StyleguidePanelBorderDto
          - `width` number
          - `style` string
          - `color` string: A hex color, or rgba() when the border is translucent.
        - `radius` string
        - `background` string
        - `shadow` string
        - `decoration` StyleguideDecorationDto
          - `kind` 'pattern' | 'fill' | 'outline', required: A layer the site draws behind or beside its panels: a patterned image, a solid block or an outline, offset to read as a shadow.
          - `offsetX` number
          - `offsetY` number
          - `image` string: The pattern's image on the site's own server. Recreate it rather than linking to it.
          - `color` string
        - `padding` string: Vertical then horizontal padding.
        - `color` string: Text color inside the panel.
        - `count` number: How many boxes on the page share this treatment.
        - `css` string: The panel as CSS declarations. A patterned decoration is not included; read `decoration` for it.
      - `header` StyleguideHeaderDto
        - `background` string, required
        - `color` string
        - `height` number
        - `sticky` boolean: Whether the bar stays pinned while the page scrolls.
        - `borderBottom` StyleguideHeaderBorderDto
          - `width` number
          - `color` string
        - `css` string
      - `headingOnPanel` 'on-border' | 'inside' | 'above': Where a panel's title sits: across its top border like a fieldset legend, inside its padding, or just above it.
      - `tabs` StyleguideTabsDto
        - `active` StyleguideTabDto
          - `background` string
          - `color` string, required
          - `fontWeight` string
          - `radius` string
          - `border` StyleguideHeaderBorderDto
            - `width` number
            - `color` string
          - `borderBottom` StyleguideHeaderBorderDto
            - `width` number
            - `color` string
          - `css` string
        - `inactive` StyleguideTabDto
          - `background` string
          - `color` string, required
          - `fontWeight` string
          - `radius` string
          - `border` StyleguideHeaderBorderDto
            - `width` number
            - `color` string
          - `borderBottom` StyleguideHeaderBorderDto
            - `width` number
            - `color` string
          - `css` string
      - `band` StyleguideBandDto
        - `background` string, required
        - `color` string
        - `count` number
    - `colors` StyleguideColorDto[], required
      - `hex` string, required
      - `name` string
      - `role` 'background' | 'surface' | 'text' | 'accent', required: Roles rather than a ranked list, so a colour drops straight into a theme instead of leaving you to guess which one is safe behind text.
    - `typography` StyleguideFontDto[], required
      - `role` 'h1' | 'h2' | 'h3' | 'h4' | 'body' | 'link', required
      - `family` string, required
      - `size` number: Computed size in pixels.
      - `weight` object, nullable
      - `lineHeight` number
      - `letterSpacing` string
      - `fallbacks` string[]: The rest of the declared stack, for rendering before the webfont arrives.
    - `webfonts` object: Keyed by family name.
    - `fontUsage` StyleguideFontUsageDto[]
      - `family` string, required
      - `words` number, required
      - `percentWords` number, required
    - `radius` StyleguideRadiusDto
      - `default` string
      - `card` string
      - `button` string
    - `shadows` object: Keyed by size, for example `sm`, `md`, `lg`.
    - `spacing` object: Keyed by step, for example `xs` through `xl`.
    - `button` StyleguideButtonDto
      - `background` string: The fill. Absent on an outlined button, which has only a border.
      - `color` object, nullable
      - `radius` string, required
      - `paddingX` number
      - `paddingY` number
      - `fontWeight` object, nullable
      - `fontSize` number
      - `minWidth` number: Width of the sampled button as it rendered, not a minimum the site sets. A button centring its label with flex has no padding to report, so this is the size to copy.
      - `minHeight` number: Height of the sampled button as it rendered, not a minimum the site sets.
      - `border` StyleguideButtonBorderDto
        - `width` number, required
        - `style` string, required
        - `color` object, nullable, required
      - `shadow` string
      - `css` string: The same button as CSS declarations you can paste into a rule.
    - `secondaryButton` StyleguideButtonDto
      - `background` string: The fill. Absent on an outlined button, which has only a border.
      - `color` object, nullable
      - `radius` string, required
      - `paddingX` number
      - `paddingY` number
      - `fontWeight` object, nullable
      - `fontSize` number
      - `minWidth` number: Width of the sampled button as it rendered, not a minimum the site sets. A button centring its label with flex has no padding to report, so this is the size to copy.
      - `minHeight` number: Height of the sampled button as it rendered, not a minimum the site sets.
      - `border` StyleguideButtonBorderDto
        - `width` number, required
        - `style` string, required
        - `color` object, nullable, required
      - `shadow` string
      - `css` string: The same button as CSS declarations you can paste into a rule.
    - `contrast` StyleguideContrastDto
      - `textOnBackground` number: Contrast ratio of text against background.
      - `meetsAA` boolean: Whether that ratio clears WCAG AA.
      - `accentOnBackground` number
    - `resolvedAt` object, nullable, required
    - `css` string: The same design as a stylesheet you can paste in: `@font-face` rules for the webfonts and a `:root` block of CSS variables for colors, fonts, the type scale, radius, shadows and spacing. Values that are not plain colors, lengths, font names or https font files are left out.
    - `tailwind` string: The same tokens as a Tailwind CSS v4 stylesheet. Paste it as your main CSS file and classes such as `bg-accent`, `font-heading`, `text-h1`, `rounded-button` and `shadow-md` use the site's design.
    - `shadcn` string: The colors, radius and fonts under shadcn/ui variable names (`--background`, `--foreground`, `--primary`, `--card`, `--muted`, `--border` and the rest). Replace the `:root` block in a shadcn project's globals.css with it.

## Other responses

- `400`: The request body or query failed validation.
- `401`: The X-API-Key header is missing, malformed, or names a key that no longer exists.
- `402`: The workspace has no credits left for this request. Nothing was charged and nothing was fetched.
- `403`: The key is valid but the workspace may not make this request.
- `404`: No such job, or the id belongs to another workspace.
- `422`: The target site did not respond, or we could not read that page. This is a fact about that URL rather than a fault on our side, and retrying it will not change the answer. When details.retryAfterSeconds is present, asking again before then returns this same answer. Nothing was charged.
- `429`: The workspace exceeded its per-minute request limit. Read the RateLimit headers, or Retry-After on this response, and retry after the window resets.
- `500`: Unexpected server error. Nothing was charged.
- `503`: A dependency needed for the requested formats is unavailable. Safe to retry.

---

[API](https://skmtc.dev/hydrafetch/apis/hydrafetch-api.md) · [All operations](https://skmtc.dev/hydrafetch/apis/hydrafetch-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hydrafetch/apis/hydrafetch-api/revisions/b28322984b4b?raw)