Personal website

The design system behind The Key of Urala, a personal blog. It holds the design tokens, the CSS built from them, and the Astro components that posts and pages use. Its source is in systems/personal-website.

The wordmark is the coloured mark and the name in the sans at weight 500, on the canvas or on the dark surface. The mark is never inverted.

Install

Each version is a GitHub Release with the package attached. Install it from the release URL:

pnpm add https://github.com/RottenSea/design-system/releases/download/personal-website-v1.0.0/rottensea-ds-personal-website-1.0.0.tgz

Use it

Load the CSS once, in the site’s layout. index.css includes a reset and is meant for a site built with a bundler; styles.css leaves the reset out, for a plain HTML page.

---
import "@rottensea/ds-personal-website/index.css";
---

The CSS loads no fonts, because a font stylesheet pulled in by CSS would hold up the whole page while Google Fonts or jsDelivr answers. Put the Fonts component in the layout’s <head> instead. It loads the same stylesheets without blocking, and the text shows in fallback fonts until they arrive. A plain HTML page can link fonts.css, which loads them the blocking way.

---
import { Fonts } from "@rottensea/ds-personal-website/components";
---
<head>
  <Fonts />
</head>

The components are Astro components. Import one by name, or pass all of them to an MDX page so posts can use them without imports. The same map turns a post’s code fences, tables and images into CodeBlock, TableScroll and Figure:

---
import { components } from "@rottensea/ds-personal-website/components";
const { Content } = await render(post);
---
<Content components={components} />

Figure makes its placeholders with sharp, which Astro uses for its own images. With pnpm, add sharp to the site’s own dependencies, because pnpm does not expose the copy Astro installs.

Posts write components with directives such as :::tip. Add the system’s remark plugin to the unified processor so they become components, its rehype plugins for heading anchors and links to other sites, and its Shiki transformers so code fences can have a title and highlighted lines:

import { unified } from "@astrojs/markdown-remark";
import {
  rehypeDsExternalLinks,
  rehypeDsHeadingAnchors,
  remarkDsDirectives,
  shikiTransformers
} from "@rottensea/ds-personal-website/markdown";

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [remarkDsDirectives],
      rehypePlugins: [rehypeDsHeadingAnchors, [rehypeDsExternalLinks, { site: "https://example.com" }]]
    }),
    shikiConfig: {
      themes: { light: "github-light", dark: "github-dark" },
      defaultColor: false,
      transformers: shikiTransformers()
    }
  }
});

Foundations

• Colors: surfaces, text, coral, accents and hairlines
• Typography: the three faces and the type scale
• Spacing and radius: the spacing scale, page widths, breakpoints and corners
• Shadows and borders: fill, hairline and the two shadows
• Motion: durations, curves and the three primitives
• Themes: the light and dark themes and how a page switches
• Accessibility: contrast ratios and the other rules

Themes

The tokens have a light and a dark theme. The CSS reads only the data-theme attribute, so the page sets data-theme="light" or data-theme="dark" on <html> before it paints. See Themes.

Version

See the changelog for what changed in each version.