Skip to content
Shaken UI
Sign in

Typography

Save

Long-form type: headings, paragraph, lead, lists, blockquote, inline code, and links, plus a Prose wrapper that styles rendered markdown at a 68ch measure.

Category
Feedback
Version
0.1.0
Frameworks
Next.js, Vite + React
Styling
Tailwind CSS v4

Preview

Typography preview

Guides · 6 min read

Rate limits for the Deployments API

Every token can make 600 requests per minute. When you go over, the API answers with 429 and tells you when to retry. Read the response headers instead of guessing.

Reading the headers

Each response carries three headers. Remaining counts down within the current window, and the reset time is a Unix timestamp in seconds.

HeaderMeaning
x-ratelimit-limitRequests allowed per window
x-ratelimit-remainingRequests left in this window
retry-afterSeconds to wait after a 429

Backing off

When a request is limited, wait and try again with a growing delay:

  1. Wait for the number of seconds in retry-after.
  2. If the next request is also limited, double the wait, up to 60 seconds.
  3. Add a little random jitter so many workers do not retry at the same moment.
const wait = Number(res.headers.get("retry-after") ?? 1);
await sleep(Math.min(60, wait * 2 ** attempt) * 1000);

Batch jobs

  • Spread work across the window instead of sending it in one burst.
  • Use a separate token per service so one noisy job cannot starve the others. Press ⌘ K in the dashboard to create one.

We cut our 429s to zero by honoring retry-after and adding jitter. It took ten lines.


Need a higher limit for a launch? Contact support with your expected peak and we will raise it for the day.

Installation

npx @shakenui/cli add typography

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add typography --dry-run

Usage

typography-example.tsx
import { H1, InlineCode, Lead, Muted, Prose, TextLink } from "@/components/shaken/ui/typography";

export default function TypographyExample() {
  return (
    <article className="grid w-full max-w-2xl gap-4 text-left">
      <Muted>Guides · 6 min read</Muted>
      <H1>Rate limits for the Deployments API</H1>
      <Lead>
        Every token can make 600 requests per minute. When you go over, the API answers with{" "}
        <InlineCode>429</InlineCode> and tells you when to retry. Read the <TextLink href="#headers">response headers</TextLink>{" "}
        instead of guessing.
      </Lead>

      {/* Prose styles plain HTML, such as rendered markdown. */}
      <Prose className="mt-6">
        <h2 id="headers">Reading the headers</h2>
        <p>
          Each response carries three headers. <strong>Remaining</strong> counts down within the current window, and the
          reset time is a Unix timestamp in seconds.
        </p>
        <table>
          <thead>
            <tr>
              <th>Header</th>
              <th>Meaning</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>
                <code>x-ratelimit-limit</code>
              </td>
              <td>Requests allowed per window</td>
            </tr>
            <tr>
              <td>
                <code>x-ratelimit-remaining</code>
              </td>
              <td>Requests left in this window</td>
            </tr>
            <tr>
              <td>
                <code>retry-after</code>
              </td>
              <td>Seconds to wait after a 429</td>
            </tr>
          </tbody>
        </table>

        <h2>Backing off</h2>
        <p>When a request is limited, wait and try again with a growing delay:</p>
        <ol>
          <li>
            Wait for the number of seconds in <code>retry-after</code>.
          </li>
          <li>If the next request is also limited, double the wait, up to 60 seconds.</li>
          <li>Add a little random jitter so many workers do not retry at the same moment.</li>
        </ol>
        <pre>
          <code>{`const wait = Number(res.headers.get("retry-after") ?? 1);
await sleep(Math.min(60, wait * 2 ** attempt) * 1000);`}</code>
        </pre>

        <h3>Batch jobs</h3>
        <ul>
          <li>Spread work across the window instead of sending it in one burst.</li>
          <li>
            Use a separate token per service so one noisy job cannot starve the others. Press <kbd>⌘</kbd> <kbd>K</kbd> in the
            dashboard to create one.
          </li>
        </ul>
        <blockquote>
          <p>We cut our 429s to zero by honoring retry-after and adding jitter. It took ten lines.</p>
        </blockquote>
        <hr />
        <p>
          Need a higher limit for a launch? <a href="#support">Contact support</a> with your expected peak and we will raise
          it for the day.
        </p>
      </Prose>
    </article>
  );
}

API

PropTypeDefaultDescription
H1, H2, H3, H4ComponentProps<"h1" | "h2" | "h3" | "h4">—Headings on a tight 28 / 20 / 16 / 15px scale, set apart by weight and color. H2 to H4 have scroll-mt-20 for anchor links.
P, Lead, MutedComponentProps<"p">—Body paragraph (15px, 1.7 line height), the larger opening paragraph in the secondary color, and small print in the tertiary color.
List orderedbooleanfalseBulleted list by default; ordered renders an <ol> with mono, tabular numbers.
Blockquote, InlineCode, TextLinkComponentProps<"blockquote" | "code" | "a">—A quotation with a hanging quote mark (no side stripe), code on a faint well, and a link with a quiet underline that strengthens on hover.
Prose fullWidthbooleanfalseProse styles plain HTML children (rendered markdown or CMS output). fullWidth removes the 68ch cap.

Accessibility

  • Uses real heading, list, blockquote, code, kbd, and table elements, so the outline and semantics come from the markup.
  • Body text is zinc-700 on white and zinc-300 on black, comfortably above WCAG AA for long reading.
  • Links are underlined (not color alone) and get the sky focus ring on keyboard focus.
  • Every reading block is capped at 68ch to keep lines readable.
  • The decorative quote mark is aria-hidden in Blockquote and generated content in Prose; only the hover underline color transitions, and that is removed under reduced motion.

Files

Installed into src/components/shaken, or components/shaken when the project has no src directory.

  • src/components/shaken/ui/typography.tsxtypography
  • npm packages: noneReact and Tailwind CSS v4 required

Source

The exact source the CLI installs, from /r/items/react/typography/0.1.0.json.

ui/typography.tsxShow
ui/typography.tsx
import type { ComponentProps } from "react";

function cx(...classes: (string | false | null | undefined)[]) {
  return classes.filter(Boolean).join(" ");
}

/*
 * Long-form type. Hierarchy comes from weight and the three text colors with a tight size
 * scale (15px body, 16 / 20 / 28px headings), not from big jumps. Body text runs a step
 * stronger than the UI secondary color (zinc-700 / zinc-300) because it is read for minutes,
 * not glanced at. Every reading block is capped at 68ch.
 *
 * The standalone parts and `Prose` share the same values; `Prose` applies them to plain
 * HTML (rendered markdown, CMS output) through descendant selectors.
 */

const measure = "max-w-[68ch]";

/** Page title. One per page. */
export function H1({ className, ...props }: ComponentProps<"h1">) {
  return (
    <h1
      className={cx(
        "text-[1.75rem] leading-[1.2] font-semibold tracking-[-0.02em] text-balance text-zinc-950 dark:text-white",
        measure,
        className,
      )}
      {...props}
    />
  );
}

/** Section heading. `scroll-mt-20` keeps anchored headings clear of a sticky header. */
export function H2({ className, ...props }: ComponentProps<"h2">) {
  return (
    <h2
      className={cx(
        "scroll-mt-20 text-xl leading-7 font-semibold tracking-[-0.01em] text-balance text-zinc-950 dark:text-white",
        measure,
        className,
      )}
      {...props}
    />
  );
}

export function H3({ className, ...props }: ComponentProps<"h3">) {
  return (
    <h3
      className={cx("scroll-mt-20 text-base leading-6 font-semibold text-balance text-zinc-950 dark:text-white", measure, className)}
      {...props}
    />
  );
}

/** The smallest heading: body size, set apart by weight alone. */
export function H4({ className, ...props }: ComponentProps<"h4">) {
  return (
    <h4
      className={cx("scroll-mt-20 text-[15px] leading-6 font-semibold text-zinc-950 dark:text-white", measure, className)}
      {...props}
    />
  );
}

/** A body paragraph. */
export function P({ className, ...props }: ComponentProps<"p">) {
  return (
    <p className={cx("text-[15px] leading-[1.7] text-pretty text-zinc-700 dark:text-zinc-300", measure, className)} {...props} />
  );
}

/** The opening paragraph under a title: one step larger, in the secondary color. */
export function Lead({ className, ...props }: ComponentProps<"p">) {
  return (
    <p className={cx("text-[17px] leading-[1.6] text-pretty text-zinc-600 dark:text-zinc-400", measure, className)} {...props} />
  );
}

/** Small print and captions in the tertiary color. */
export function Muted({ className, ...props }: ComponentProps<"p">) {
  return <p className={cx("text-xs leading-5 text-zinc-500", measure, className)} {...props} />;
}

export type ListProps = (ComponentProps<"ul"> & { ordered?: false }) | (ComponentProps<"ol"> & { ordered: true });

/** A bulleted list, or a numbered one with `ordered`. Numbers are mono and tabular. */
export function List({ ordered, className, ...props }: ListProps) {
  const classes = cx(
    "grid gap-1.5 pl-5 text-[15px] leading-[1.7] text-zinc-700 dark:text-zinc-300",
    ordered
      ? "list-decimal marker:font-mono marker:text-[13px] marker:text-zinc-500 marker:tabular-nums"
      : "list-disc marker:text-zinc-400 dark:marker:text-zinc-600",
    "[&>li]:pl-1.5",
    measure,
    className,
  );
  return ordered ? (
    <ol className={classes} {...(props as ComponentProps<"ol">)} />
  ) : (
    <ul className={classes} {...(props as ComponentProps<"ul">)} />
  );
}

/**
 * A quotation set in from the text with a hanging quote mark. No side stripe: the indent,
 * the mark, and the secondary color set it apart.
 */
export function Blockquote({ className, children, ...props }: ComponentProps<"blockquote">) {
  return (
    <blockquote
      className={cx("relative pl-6 text-[15px] leading-[1.7] text-pretty text-zinc-600 dark:text-zinc-400", measure, className)}
      {...props}
    >
      <span aria-hidden="true" className="absolute top-0 left-0 text-[1.6em] leading-[1.1] font-medium text-zinc-300 select-none dark:text-zinc-600">
        &ldquo;
      </span>
      {children}
    </blockquote>
  );
}

/** Code inside a sentence: mono, on a faint well. */
export function InlineCode({ className, ...props }: ComponentProps<"code">) {
  return (
    <code
      className={cx(
        "rounded-md border border-zinc-950/[0.08] bg-zinc-950/[0.03] px-[0.35em] py-px font-mono text-[0.86em] text-zinc-950",
        "dark:border-white/[0.1] dark:bg-transparent dark:text-white",
        className,
      )}
      {...props}
    />
  );
}

/** An inline link: primary color with a quiet underline that strengthens on hover. */
export function TextLink({ className, ...props }: ComponentProps<"a">) {
  return (
    <a
      className={cx(
        "rounded-[2px] font-medium text-zinc-950 underline decoration-zinc-950/25 decoration-1 underline-offset-[3px]",
        "transition-[text-decoration-color] duration-150 ease-out hover:decoration-zinc-950 motion-reduce:transition-none",
        "dark:text-white dark:decoration-white/30 dark:hover:decoration-white",
        "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500",
        className,
      )}
      {...props}
    />
  );
}

// Descendant styles for `Prose`, grouped by element. Same values as the parts above.
const prose = cx(
  // Base and measure
  "text-[15px] leading-[1.7] text-pretty text-zinc-700 dark:text-zinc-300",
  measure,
  "[&>:first-child]:mt-0 [&>:last-child]:mb-0",
  // Headings
  "[&_h1]:mt-0 [&_h1]:mb-4 [&_h1]:text-[1.75rem] [&_h1]:leading-[1.2] [&_h1]:font-semibold [&_h1]:tracking-[-0.02em] [&_h1]:text-balance [&_h1]:text-zinc-950 dark:[&_h1]:text-white",
  "[&_h2]:mt-12 [&_h2]:mb-3 [&_h2]:scroll-mt-20 [&_h2]:text-xl [&_h2]:leading-7 [&_h2]:font-semibold [&_h2]:tracking-[-0.01em] [&_h2]:text-balance [&_h2]:text-zinc-950 dark:[&_h2]:text-white",
  "[&_h3]:mt-9 [&_h3]:mb-2 [&_h3]:scroll-mt-20 [&_h3]:text-base [&_h3]:leading-6 [&_h3]:font-semibold [&_h3]:text-zinc-950 dark:[&_h3]:text-white",
  "[&_h4]:mt-7 [&_h4]:mb-2 [&_h4]:scroll-mt-20 [&_h4]:text-[15px] [&_h4]:leading-6 [&_h4]:font-semibold [&_h4]:text-zinc-950 dark:[&_h4]:text-white",
  // A heading straight after another heading sits closer.
  "[&_:is(h1,h2,h3,h4)+:is(h2,h3,h4)]:mt-3",
  // Paragraphs, lead, small print
  "[&_p]:my-5",
  "[&_.lead]:text-[17px] [&_.lead]:leading-[1.6] [&_.lead]:text-zinc-600 dark:[&_.lead]:text-zinc-400",
  "[&_small]:text-xs [&_small]:text-zinc-500",
  "[&_strong]:font-semibold [&_strong]:text-zinc-950 dark:[&_strong]:text-white",
  // Links
  "[&_a]:rounded-[2px] [&_a]:font-medium [&_a]:text-zinc-950 [&_a]:underline [&_a]:decoration-zinc-950/25 [&_a]:decoration-1 [&_a]:underline-offset-[3px]",
  "[&_a]:transition-[text-decoration-color] [&_a]:duration-150 [&_a]:ease-out [&_a:hover]:decoration-zinc-950 motion-reduce:[&_a]:transition-none",
  "dark:[&_a]:text-white dark:[&_a]:decoration-white/30 dark:[&_a:hover]:decoration-white",
  "[&_a:focus-visible]:outline-2 [&_a:focus-visible]:outline-offset-2 [&_a:focus-visible]:outline-sky-500",
  // Lists
  "[&_ul]:my-5 [&_ul]:list-disc [&_ul]:pl-5 [&_ul_li]:marker:text-zinc-400 dark:[&_ul_li]:marker:text-zinc-600",
  "[&_ol]:my-5 [&_ol]:list-decimal [&_ol]:pl-5 [&_ol_li]:marker:font-mono [&_ol_li]:marker:text-[13px] [&_ol_li]:marker:text-zinc-500 [&_ol_li]:marker:tabular-nums",
  "[&_li]:my-1.5 [&_li]:pl-1.5 [&_li>p]:my-0 [&_li>:is(ul,ol)]:my-1.5",
  // Blockquote: indent and a hanging quote mark, no side stripe.
  "[&_blockquote]:relative [&_blockquote]:my-6 [&_blockquote]:pl-6 [&_blockquote]:text-zinc-600 dark:[&_blockquote]:text-zinc-400 [&_blockquote_p]:my-2",
  "[&_blockquote]:before:absolute [&_blockquote]:before:top-0 [&_blockquote]:before:left-0 [&_blockquote]:before:text-[1.6em] [&_blockquote]:before:leading-[1.1] [&_blockquote]:before:font-medium [&_blockquote]:before:text-zinc-300 [&_blockquote]:before:content-['“'] dark:[&_blockquote]:before:text-zinc-600",
  // Code
  "[&_:not(pre)>code]:rounded-md [&_:not(pre)>code]:border [&_:not(pre)>code]:border-zinc-950/[0.08] [&_:not(pre)>code]:bg-zinc-950/[0.03] [&_:not(pre)>code]:px-[0.35em] [&_:not(pre)>code]:py-px",
  "[&_code]:font-mono [&_code]:text-[0.86em] [&_code]:text-zinc-950 dark:[&_:not(pre)>code]:border-white/[0.1] dark:[&_:not(pre)>code]:bg-transparent dark:[&_code]:text-white",
  "[&_pre]:my-6 [&_pre]:overflow-x-auto [&_pre]:rounded-lg [&_pre]:border [&_pre]:border-zinc-950/[0.07] [&_pre]:bg-zinc-950/[0.02] [&_pre]:p-4 [&_pre]:text-[13px] [&_pre]:leading-relaxed",
  "dark:[&_pre]:border-white/[0.08] dark:[&_pre]:bg-transparent [&_pre_code]:text-[1em] [&_pre_code]:text-zinc-800 dark:[&_pre_code]:text-zinc-200",
  "[&_kbd]:rounded-md [&_kbd]:border [&_kbd]:border-zinc-950/12 [&_kbd]:px-1.5 [&_kbd]:py-px [&_kbd]:font-mono [&_kbd]:text-[0.8em] [&_kbd]:text-zinc-950 dark:[&_kbd]:border-white/15 dark:[&_kbd]:text-white",
  // Rules, media, tables
  "[&_hr]:my-10 [&_hr]:border-zinc-950/[0.07] dark:[&_hr]:border-white/[0.08]",
  "[&_img]:my-6 [&_img]:rounded-xl [&_img]:border [&_img]:border-zinc-950/10 dark:[&_img]:border-white/10",
  "[&_figure]:my-6 [&_figure_img]:my-0 [&_figcaption]:mt-2 [&_figcaption]:text-xs [&_figcaption]:text-zinc-500",
  "[&_table]:my-6 [&_table]:w-full [&_table]:border-collapse [&_table]:text-sm [&_table]:leading-5",
  "[&_th]:border-b [&_th]:border-zinc-950/10 [&_th]:py-2 [&_th]:pr-4 [&_th]:text-left [&_th]:text-xs [&_th]:font-medium [&_th]:text-zinc-500 dark:[&_th]:border-white/10",
  "[&_td]:border-b [&_td]:border-zinc-950/[0.07] [&_td]:py-2.5 [&_td]:pr-4 [&_td]:align-top dark:[&_td]:border-white/[0.08]",
);

export interface ProseProps extends ComponentProps<"div"> {
  /** Removes the 68ch cap, for a container that already sets its own width. */
  fullWidth?: boolean;
}

/**
 * Styles arbitrary long-form HTML (rendered markdown, CMS fields) with the same type as the
 * parts above: headings, paragraphs, `p.lead`, lists, blockquotes, links, inline and block
 * code, `kbd`, rules, images, figures, and tables.
 */
export function Prose({ fullWidth = false, className, ...props }: ProseProps) {
  return <div className={cx(prose, fullWidth && "max-w-none", className)} {...props} />;
}