diff --git a/README.md b/README.md
index 15aa0aa..bd6d940 100644
--- a/README.md
+++ b/README.md
@@ -190,9 +190,45 @@ no tokens shipped, no client-side API calls, no CORS.
 
 ## Styling
 
-Components use [Infima](https://infima.dev/) CSS variables, so they inherit your
-site's theme (including dark mode) automatically. They're exported as normal
-components, so you can wrap or restyle them as needed.
+The components ship **without any bundled CSS** — they render plain, stable class
+names so you stay in full control of the look. The package includes an optional,
+light/dark-aware theme (`theme.css`) you can apply as-is or use as a starting
+point. It's built on [Infima](https://infima.dev/) variables, so it tracks your
+site's active theme automatically.
+
+Apply it from your `classic` preset's `theme.customCss`:
+
+```ts
+// docusaurus.config.ts (ESM)
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+
+// ...inside the classic preset options:
+theme: {
+  customCss: require.resolve("@ebuildy/docusaurus-plugin-gitlab/theme.css"),
+},
+```
+
+Prefer to own the CSS? Copy
+[`theme.css`](https://github.com/ebuildy/docusaurus-plugin-gitlab/blob/main/theme.css)
+into your `src/css/custom.css` and edit freely. The class names you can target:
+
+| Class | Element |
+|---|---|
+| `gitlab-card` | `<GitlabProjectInfo>` container |
+| `gitlab-card-header` | avatar + title row |
+| `gitlab-avatar` | project avatar image |
+| `gitlab-title` | project / release title |
+| `gitlab-muted` | secondary text (dates, authors, descriptions) |
+| `gitlab-badge` | topics, tags, labels, release assets |
+| `gitlab-stats` | stars / forks / updated row |
+| `gitlab-issues` / `gitlab-issue` | issues list + each issue row |
+| `gitlab-issue-state` / `gitlab-issue-title` | issue state badge (`data-state`) + title link |
+| `gitlab-releases` / `gitlab-release` | releases list + each release card |
+| `gitlab-release-notes` / `gitlab-release-assets` | release body + asset links |
+| `gitlab-readme` | rendered README / markdown file |
+| `gitlab-fallback` | error fallback box |
+| `gitlab-code` / `gitlab-code-title` / `gitlab-code-pre` | code file embed |
 
 ## Development
 
diff --git a/docs/superpowers/plans/2026-06-28-card-theme.md b/docs/superpowers/plans/2026-06-28-card-theme.md
new file mode 100644
index 0000000..f3e1591
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-28-card-theme.md
@@ -0,0 +1,705 @@
+# Card UI theme + project avatar Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a toggleable, light/dark-aware "minimal but beautiful" card theme (one boolean plugin option) and show the project avatar in the project-overview card.
+
+**Architecture:** A new Docusaurus plugin injects one inline `<style>` that defines private `--gl-card-*` CSS variables on `:root` (plus a `[data-theme='dark']` override). The components' CSS module reads those variables with fallbacks equal to today's look, so `theme: false` is visually unchanged and dark mode rides on Docusaurus's existing `data-theme` attribute. Separately, `fetchProjectInfo` localizes the project avatar via the existing `AssetManager`, and `GitlabProjectInfo` renders it.
+
+**Tech Stack:** TypeScript (ESM-only, `.js` import extensions), Joi (validation), Vitest + React Testing Library, tsup. Spec: `docs/superpowers/specs/2026-06-28-card-theme-design.md`.
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|---|---|
+| `src/plugin/theme.ts` (new) | `resolveTheme(input)` (Joi validate + default), `renderThemeCss()` (pure CSS string), `GL_CARD_VARS` (the var-name list — single source of truth). |
+| `src/plugin/theme.test.ts` (new) | Unit tests for `resolveTheme` / `renderThemeCss` + the CSS-module sync guard. |
+| `src/plugin/index.ts` (new) | Docusaurus plugin `docusaurusGitlabTheme(context, options)` → `injectHtmlTags()`. |
+| `src/plugin/index.test.ts` (new) | Unit tests for `injectHtmlTags` (enabled vs disabled). |
+| `src/components/styles.module.css` (modify) | Read `var(--gl-card-*, <current value>)` so fallbacks reproduce today's look; add subtle hover + avatar class. |
+| `package.json` (modify) | Add `./plugin` export subpath. |
+| `tsup.config.ts` (modify) | Add `src/plugin/index.ts` entry. |
+| `test/packaging.test.ts` (modify) | Add `./plugin` to the guarded subpaths. |
+| `src/gitlab/fetchers.ts` (modify) | `fetchProjectInfo`: localize `p.avatar_url` when present. |
+| `src/gitlab/fetchers.test.ts` (modify) | Tests for avatar localization (present / null). |
+| `src/components/GitlabProjectInfo.tsx` (modify) | Render rounded avatar `<img>` when `avatarUrl` set. |
+| `src/components/GitlabProjectInfo.test.tsx` (modify) | Tests for avatar render (present / null). |
+| `examples/site/docusaurus.config.ts` (modify) | Register the plugin in `plugins: []`. |
+| `README.md` (modify) | Document the card theme option. |
+
+---
+
+## Task 1: Theme CSS builder (`src/plugin/theme.ts`)
+
+**Files:**
+- Create: `src/plugin/theme.ts`
+- Test: `src/plugin/theme.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/plugin/theme.test.ts`:
+
+```ts
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, it, expect } from "vitest";
+import { resolveTheme, renderThemeCss, GL_CARD_VARS } from "./theme.js";
+
+describe("resolveTheme", () => {
+  it("defaults to enabled when no option is given", () => {
+    expect(resolveTheme(undefined)).toEqual({ enabled: true });
+    expect(resolveTheme({})).toEqual({ enabled: true });
+  });
+
+  it("respects theme: false", () => {
+    expect(resolveTheme({ theme: false })).toEqual({ enabled: false });
+  });
+
+  it("throws on a non-boolean theme", () => {
+    expect(() => resolveTheme({ theme: "yes" as any })).toThrow(
+      /@ebuildy\/docusaurus-plugin-gitlab/,
+    );
+  });
+
+  it("throws on unknown keys", () => {
+    expect(() => resolveTheme({ accent: "#fff" } as any)).toThrow(
+      /@ebuildy\/docusaurus-plugin-gitlab/,
+    );
+  });
+});
+
+describe("renderThemeCss", () => {
+  const css = renderThemeCss();
+
+  it("defines every --gl-card-* var on :root", () => {
+    expect(css).toMatch(/:root\s*\{/);
+    for (const v of GL_CARD_VARS) {
+      expect(css, `missing ${v}`).toContain(`${v}:`);
+    }
+  });
+
+  it("references --ifm-* theme variables for colors", () => {
+    expect(css).toContain("var(--ifm-color-primary)");
+    expect(css).toContain("var(--ifm-background-surface-color)");
+  });
+
+  it("includes a dark-mode override block", () => {
+    expect(css).toContain("[data-theme='dark']");
+  });
+
+  it("uses no hardcoded hex palette colors", () => {
+    expect(css).not.toMatch(/#[0-9a-fA-F]{3,8}\b/);
+  });
+});
+
+describe("CSS module stays in sync with the theme vars", () => {
+  it("references every --gl-card-* var", () => {
+    const cssPath = fileURLToPath(
+      new URL("../components/styles.module.css", import.meta.url),
+    );
+    const moduleCss = readFileSync(cssPath, "utf8");
+    for (const v of GL_CARD_VARS) {
+      expect(moduleCss, `styles.module.css does not use ${v}`).toContain(v);
+    }
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/plugin/theme.test.ts`
+Expected: FAIL — cannot resolve `./theme.js` (module does not exist).
+
+- [ ] **Step 3: Write the implementation**
+
+Create `src/plugin/theme.ts`:
+
+```ts
+import Joi from "joi";
+
+export interface GitlabThemeOptions {
+  /** Inject the polished card theme. Default: true. */
+  theme?: boolean;
+}
+
+export interface ResolvedTheme {
+  enabled: boolean;
+}
+
+/** Private CSS variables the theme defines and the component CSS consumes. */
+export const GL_CARD_VARS = [
+  "--gl-card-bg",
+  "--gl-card-border",
+  "--gl-card-radius",
+  "--gl-card-shadow",
+  "--gl-card-accent",
+  "--gl-card-badge-bg",
+] as const;
+
+const schema = Joi.object({
+  theme: Joi.boolean().optional(),
+});
+
+export function resolveTheme(input: GitlabThemeOptions | undefined): ResolvedTheme {
+  const { error, value } = schema.validate(input ?? {}, { abortEarly: false });
+  if (error) {
+    throw new Error(
+      `@ebuildy/docusaurus-plugin-gitlab: invalid theme options — ${error.message}`,
+    );
+  }
+  return { enabled: (value as GitlabThemeOptions).theme ?? true };
+}
+
+export function renderThemeCss(): string {
+  return `:root {
+  --gl-card-bg: var(--ifm-background-surface-color);
+  --gl-card-border: var(--ifm-color-emphasis-200);
+  --gl-card-radius: 10px;
+  --gl-card-shadow: 0 1px 2px rgb(0 0 0 / 0.06), 0 2px 8px rgb(0 0 0 / 0.04);
+  --gl-card-accent: var(--ifm-color-primary);
+  --gl-card-badge-bg: var(--ifm-color-emphasis-100);
+}
+[data-theme='dark'] {
+  --gl-card-border: var(--ifm-color-emphasis-300);
+  --gl-card-shadow: 0 1px 2px rgb(0 0 0 / 0.3), 0 2px 10px rgb(0 0 0 / 0.25);
+}
+`;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run src/plugin/theme.test.ts`
+Expected: PASS for `resolveTheme` and `renderThemeCss` groups. The "CSS module stays in sync" test will still FAIL (the module does not reference the vars yet) — that is fixed in Task 3. To confirm only the sync test fails here, the failure message must be `styles.module.css does not use --gl-card-...`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/plugin/theme.ts src/plugin/theme.test.ts
+git commit -m "feat: add card theme CSS builder and option validation
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 2: Docusaurus plugin (`src/plugin/index.ts`)
+
+**Files:**
+- Create: `src/plugin/index.ts`
+- Test: `src/plugin/index.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/plugin/index.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import docusaurusGitlabTheme from "./index.js";
+
+const ctx = {} as any;
+
+describe("docusaurusGitlabTheme", () => {
+  it("has the package name", () => {
+    const plugin = docusaurusGitlabTheme(ctx, {});
+    expect(plugin.name).toBe("docusaurus-plugin-gitlab-theme");
+  });
+
+  it("injects a style tag with the card vars when enabled", () => {
+    const plugin = docusaurusGitlabTheme(ctx, { theme: true });
+    const tags = plugin.injectHtmlTags!({ content: undefined });
+    const head = (tags.headTags ?? []) as any[];
+    expect(head).toHaveLength(1);
+    expect(head[0].tagName).toBe("style");
+    expect(head[0].innerHTML).toContain("--gl-card-shadow");
+    expect(head[0].innerHTML).toContain("[data-theme='dark']");
+  });
+
+  it("injects nothing when theme is false", () => {
+    const plugin = docusaurusGitlabTheme(ctx, { theme: false });
+    const tags = plugin.injectHtmlTags!({ content: undefined });
+    expect(tags.headTags ?? []).toHaveLength(0);
+  });
+
+  it("throws on invalid options", () => {
+    expect(() => docusaurusGitlabTheme(ctx, { theme: "x" } as any)).toThrow(
+      /@ebuildy\/docusaurus-plugin-gitlab/,
+    );
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/plugin/index.test.ts`
+Expected: FAIL — cannot resolve `./index.js`.
+
+- [ ] **Step 3: Write the implementation**
+
+Create `src/plugin/index.ts`. We define minimal local types instead of depending on `@docusaurus/types` (not a dependency of this package):
+
+```ts
+import { resolveTheme, renderThemeCss, type GitlabThemeOptions } from "./theme.js";
+
+interface HtmlTagObject {
+  tagName: string;
+  attributes?: Record<string, string | boolean>;
+  innerHTML?: string;
+}
+
+interface InjectedHtmlTags {
+  headTags?: HtmlTagObject[];
+}
+
+interface GitlabThemePlugin {
+  name: string;
+  injectHtmlTags(args: { content: unknown }): InjectedHtmlTags;
+}
+
+export default function docusaurusGitlabTheme(
+  _context: unknown,
+  options: GitlabThemeOptions,
+): GitlabThemePlugin {
+  const { enabled } = resolveTheme(options);
+  return {
+    name: "docusaurus-plugin-gitlab-theme",
+    injectHtmlTags() {
+      if (!enabled) return {};
+      return {
+        headTags: [
+          {
+            tagName: "style",
+            attributes: { type: "text/css" },
+            innerHTML: renderThemeCss(),
+          },
+        ],
+      };
+    },
+  };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run src/plugin/index.test.ts`
+Expected: PASS (all four tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/plugin/index.ts src/plugin/index.test.ts
+git commit -m "feat: add docusaurus plugin that injects the card theme
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 3: Consume the vars in the component CSS
+
+**Files:**
+- Modify: `src/components/styles.module.css`
+
+This makes the Task 1 "CSS module stays in sync" test pass, keeps `theme: false` visually identical to today (fallbacks = current values), and adds the subtle hover and the avatar class.
+
+- [ ] **Step 1: Edit the CSS module**
+
+Replace the contents of `src/components/styles.module.css` with:
+
+```css
+.card {
+  border: 1px solid var(--gl-card-border, var(--ifm-color-emphasis-300));
+  border-radius: var(--gl-card-radius, var(--ifm-card-border-radius, 8px));
+  padding: 1rem;
+  margin: 1rem 0;
+  background: var(--gl-card-bg, var(--ifm-card-background-color, var(--ifm-background-surface-color)));
+  box-shadow: var(--gl-card-shadow, none);
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+.card:hover {
+  border-color: var(--gl-card-accent, var(--ifm-color-emphasis-300));
+}
+.header { display: flex; align-items: center; gap: 0.6rem; }
+.avatar {
+  width: 32px;
+  height: 32px;
+  border-radius: var(--gl-card-radius, 8px);
+  object-fit: cover;
+  flex: none;
+}
+.title { font-weight: 600; }
+.title a { color: var(--gl-card-accent, inherit); }
+.muted { color: var(--ifm-color-emphasis-600); }
+.stats { display: flex; gap: 1rem; margin-top: 0.5rem; }
+.badge {
+  display: inline-block;
+  padding: 0 0.5rem;
+  border-radius: 4px;
+  background: var(--gl-card-badge-bg, var(--ifm-color-emphasis-200));
+  font-size: 0.85em;
+  margin-right: 0.25rem;
+}
+.fallback {
+  border-left: 4px solid var(--ifm-color-warning);
+  padding: 0.75rem 1rem;
+  background: var(--ifm-color-warning-contrast-background);
+  margin: 1rem 0;
+}
+.list { list-style: none; padding: 0; margin: 1rem 0; }
+.listItem { padding: 0.5rem 0; border-bottom: 1px solid var(--ifm-color-emphasis-200); }
+.readme :global(img) { max-width: 100%; }
+.codeBlock {
+  margin: 1rem 0;
+  border: 1px solid var(--gl-card-border, var(--ifm-color-emphasis-300));
+  border-radius: var(--gl-card-radius, var(--ifm-code-border-radius, 6px));
+  overflow: hidden;
+}
+.codeTitle {
+  padding: 0.4rem 1rem;
+  font-size: 0.85em;
+  font-family: var(--ifm-font-family-monospace);
+  color: var(--ifm-color-emphasis-700);
+  background: var(--ifm-color-emphasis-100);
+  border-bottom: 1px solid var(--gl-card-border, var(--ifm-color-emphasis-300));
+}
+.codePre {
+  margin: 0;
+  padding: 1rem;
+  overflow: auto;
+  font-size: var(--ifm-code-font-size, 90%);
+}
+```
+
+- [ ] **Step 2: Run the theme test to verify the sync guard passes**
+
+Run: `npx vitest run src/plugin/theme.test.ts`
+Expected: PASS (all groups now, including "CSS module stays in sync").
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/components/styles.module.css
+git commit -m "feat: drive card styles from --gl-card-* theme variables
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 4: Ship the `/plugin` export
+
+**Files:**
+- Modify: `package.json`
+- Modify: `tsup.config.ts`
+- Modify: `test/packaging.test.ts`
+
+- [ ] **Step 1: Add `./plugin` to the packaging guard test**
+
+In `test/packaging.test.ts`, change the `subpaths` line (currently line 24):
+
+```ts
+  const subpaths = [".", "./remark", "./components", "./plugin"];
+```
+
+- [ ] **Step 2: Run the packaging test to verify it fails**
+
+Run: `npx vitest run test/packaging.test.ts`
+Expected: FAIL — `missing export "./plugin"`.
+
+- [ ] **Step 3: Add the export to `package.json`**
+
+In `package.json`, inside `"exports"`, after the `"./components"` block, add:
+
+```json
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js",
+      "default": "./dist/plugin/index.js"
+    }
+```
+
+(Add a comma after the preceding `"./components"` block so the JSON stays valid.)
+
+- [ ] **Step 4: Add the tsup entry**
+
+In `tsup.config.ts`, update the `entry` array:
+
+```ts
+  entry: ["src/index.ts", "src/remark/index.ts", "src/components/index.ts", "src/plugin/index.ts"],
+```
+
+- [ ] **Step 5: Run the packaging test to verify it passes**
+
+Run: `npx vitest run test/packaging.test.ts`
+Expected: PASS.
+
+- [ ] **Step 6: Build to confirm the entry compiles**
+
+Run: `npm run build`
+Expected: tsup emits `dist/plugin/index.js` and `dist/plugin/index.d.ts` with no errors.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add package.json tsup.config.ts test/packaging.test.ts
+git commit -m "build: expose @ebuildy/docusaurus-plugin-gitlab/plugin entry
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 5: Localize the project avatar in the fetcher
+
+**Files:**
+- Modify: `src/gitlab/fetchers.ts` (`fetchProjectInfo`, around lines 30-47)
+- Test: `src/gitlab/fetchers.test.ts` (`fetchProjectInfo` describe block, lines 18-30)
+
+- [ ] **Step 1: Write the failing tests**
+
+In `src/gitlab/fetchers.test.ts`, replace the existing `describe("fetchProjectInfo", ...)` block (lines 18-30) with:
+
+```ts
+describe("fetchProjectInfo", () => {
+  it("normalizes the project payload", async () => {
+    const client = {
+      getProject: vi.fn(async () => ({
+        id: 7, path_with_namespace: "g/r", name: "r", description: "d", web_url: "https://gitlab.com/g/r",
+        star_count: 3, forks_count: 1, topics: ["x"], last_activity_at: "2026-01-01T00:00:00Z", avatar_url: null,
+      })),
+    };
+    const c = ctx(client);
+    const data = await fetchProjectInfo(c, { project: "g/r" });
+    expect(data).toMatchObject({ id: 7, path: "g/r", starCount: 3, topics: ["x"] });
+    expect(data.avatarUrl).toBeNull();
+    expect(c.assets.localize).not.toHaveBeenCalled();
+    expect(client.getProject).toHaveBeenCalledWith("g/r");
+  });
+
+  it("localizes the avatar when the project has one", async () => {
+    const client = {
+      getProject: vi.fn(async () => ({
+        id: 7, path_with_namespace: "g/r", name: "r", description: "d", web_url: "https://gitlab.com/g/r",
+        star_count: 3, forks_count: 1, topics: ["x"], last_activity_at: "2026-01-01T00:00:00Z",
+        avatar_url: "https://gitlab.com/uploads/avatar.png",
+      })),
+    };
+    const c = ctx(client);
+    const data = await fetchProjectInfo(c, { project: "g/r" });
+    expect(c.assets.localize).toHaveBeenCalledWith("https://gitlab.com/uploads/avatar.png", "", "g/r");
+    expect(data.avatarUrl).toBe("/gitlab-assets/httpsgitlabcomuploadsavatarpng.png");
+  });
+});
+```
+
+(The expected localized string matches the fake `localize` in `ctx()`: `` `/gitlab-assets/${src.replace(/\W/g, "")}.png` ``.)
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `npx vitest run src/gitlab/fetchers.test.ts -t fetchProjectInfo`
+Expected: FAIL — `localize` not called / `avatarUrl` is the raw remote URL.
+
+- [ ] **Step 3: Update `fetchProjectInfo`**
+
+In `src/gitlab/fetchers.ts`, replace the body of the `memo(...)` callback in `fetchProjectInfo` (lines 32-46) so the avatar is localized:
+
+```ts
+  return memo(ctx, `projectInfo:${project}`, async () => {
+    const p = await ctx.client.getProject(attrs.project as string | number);
+    const avatarUrl = p.avatar_url
+      ? await ctx.assets.localize(p.avatar_url, "", project)
+      : null;
+    return {
+      id: p.id,
+      path: p.path_with_namespace,
+      name: p.name,
+      description: p.description ?? null,
+      webUrl: p.web_url,
+      starCount: p.star_count,
+      forksCount: p.forks_count,
+      topics: p.topics ?? [],
+      lastActivityAt: p.last_activity_at,
+      avatarUrl,
+    } satisfies ProjectInfoData;
+  }).then((v) => ({ ...v, path: v.path || project }));
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `npx vitest run src/gitlab/fetchers.test.ts -t fetchProjectInfo`
+Expected: PASS (both tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/gitlab/fetchers.ts src/gitlab/fetchers.test.ts
+git commit -m "feat: localize project avatar at build time
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 6: Render the avatar in `GitlabProjectInfo`
+
+**Files:**
+- Modify: `src/components/GitlabProjectInfo.tsx`
+- Test: `src/components/GitlabProjectInfo.test.tsx`
+
+- [ ] **Step 1: Write the failing tests**
+
+In `src/components/GitlabProjectInfo.test.tsx`, add these two tests inside the existing `describe("GitlabProjectInfo", ...)` block (after the existing tests):
+
+```ts
+  it("renders the avatar when avatarUrl is set", () => {
+    render(<GitlabProjectInfo data={{ ...data, avatarUrl: "/gitlab-assets/a.png" } as any} />);
+    const img = screen.getByRole("img", { name: "My Repo" });
+    expect(img).toHaveAttribute("src", "/gitlab-assets/a.png");
+  });
+
+  it("renders no avatar when avatarUrl is null", () => {
+    render(<GitlabProjectInfo data={data as any} />);
+    expect(screen.queryByRole("img")).not.toBeInTheDocument();
+  });
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `npx vitest run src/components/GitlabProjectInfo.test.tsx`
+Expected: FAIL — no `img` is rendered.
+
+- [ ] **Step 3: Update the component**
+
+Replace the `return (...)` JSX in `src/components/GitlabProjectInfo.tsx` so the title sits in a header row with the optional avatar:
+
+```tsx
+  return (
+    <div className={styles.card}>
+      <div className={styles.header}>
+        {data.avatarUrl && (
+          <img
+            className={styles.avatar}
+            src={data.avatarUrl}
+            alt={data.name}
+            width={32}
+            height={32}
+          />
+        )}
+        <div className={styles.title}>
+          <a href={data.webUrl}>{data.name}</a>
+        </div>
+      </div>
+      {data.description && <p className={styles.muted}>{data.description}</p>}
+      {data.topics.length > 0 && (
+        <div>
+          {data.topics.map((t) => (
+            <span key={t} className={styles.badge}>{t}</span>
+          ))}
+        </div>
+      )}
+      {showStats && (
+        <div className={styles.stats}>
+          <span>★ {data.starCount}</span>
+          <span>⑂ {data.forksCount}</span>
+          <span className={styles.muted}>updated {new Date(data.lastActivityAt).toLocaleDateString()}</span>
+        </div>
+      )}
+    </div>
+  );
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `npx vitest run src/components/GitlabProjectInfo.test.tsx`
+Expected: PASS (all four tests, including the original name/description/stats and fallback tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/components/GitlabProjectInfo.tsx src/components/GitlabProjectInfo.test.tsx
+git commit -m "feat: show project avatar in GitlabProjectInfo
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 7: Wire the example site, document, and verify
+
+**Files:**
+- Modify: `examples/site/docusaurus.config.ts`
+- Modify: `README.md`
+
+- [ ] **Step 1: Register the plugin in the example site**
+
+In `examples/site/docusaurus.config.ts`, add the import near the top (after the existing `remarkGitlab` import):
+
+```ts
+import docusaurusGitlabTheme from "@ebuildy/docusaurus-plugin-gitlab/plugin";
+```
+
+Then add a top-level `plugins` array to the `config` object (sibling of `presets`):
+
+```ts
+  plugins: [[docusaurusGitlabTheme, { theme: true }]],
+```
+
+- [ ] **Step 2: Document the option in the README**
+
+Add a "Card theme" section to `README.md` (place it after the existing setup/usage section). Use this content:
+
+```markdown
+## Card theme
+
+The package ships an optional Docusaurus plugin that styles the embedded GitLab
+cards with a minimal, light/dark-aware theme. Register it in `plugins`:
+
+```ts
+import docusaurusGitlabTheme from "@ebuildy/docusaurus-plugin-gitlab/plugin";
+
+// docusaurus.config.ts
+plugins: [[docusaurusGitlabTheme, { theme: true }]],
+```
+
+`theme` defaults to `true`. Set it to `false` to opt out and keep the plain
+fallback styling. The theme follows your site's active light/dark mode — it reads
+Docusaurus's own `--ifm-*` variables and ships no client-side JavaScript.
+```
+
+(Note: the inner code fence above is part of the README content — keep it as a nested fenced block.)
+
+- [ ] **Step 3: Typecheck the package**
+
+Run: `npm run typecheck`
+Expected: no errors.
+
+- [ ] **Step 4: Run the full unit test suite**
+
+Run: `npx vitest run`
+Expected: all tests pass (excludes the slow e2e, which is run next).
+
+- [ ] **Step 5: Run the e2e build (slow, ~1 min)**
+
+Run: `npx vitest run test/e2e/build.test.ts`
+Expected: PASS — the example site (now registering the theme plugin) builds successfully.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add examples/site/docusaurus.config.ts README.md
+git commit -m "docs: wire and document the card theme plugin
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Final verification
+
+- [ ] Run `npx vitest run` — all unit tests green.
+- [ ] Run `npm run typecheck` — clean.
+- [ ] Run `npm run build` — `dist/plugin/index.js` + `.d.ts` emitted.
+- [ ] Run `npx vitest run test/e2e/build.test.ts` — e2e build green.
+```
diff --git a/docs/superpowers/specs/2026-06-28-card-theme-design.md b/docs/superpowers/specs/2026-06-28-card-theme-design.md
new file mode 100644
index 0000000..8c5cc14
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-28-card-theme-design.md
@@ -0,0 +1,170 @@
+# Card UI theme + project avatar — design
+
+## Goal
+
+Ship a small, opinionated "minimal but beautiful" card theme for the
+`@ebuildy/docusaurus-plugin-gitlab` components. It must be:
+
+- **Toggleable from plugin config** with a single boolean — no token tuning.
+- **Light/dark aware**, following the host site's active Docusaurus theme.
+- **Pure CSS / SSR-safe** — no client JS, no flash, consistent with the
+  build-time / static-HTML philosophy in `CLAUDE.md`.
+
+## Non-goals
+
+- No configurable design tokens (accent, radius, elevation, density). Explicitly
+  cut — the theme is one opinionated look.
+- No `{ light, dark }` config pairs and no `--gl-card-*` token system.
+- No changes to the component `.tsx` files or their class names *for theming*
+  (the avatar addition below does touch `GitlabProjectInfo.tsx`).
+- No automatic MDX component registration (users still register components via
+  `MDXComponents` as today).
+- No *user-facing* design tokens. The internal `--gl-card-*` CSS variables below
+  are private plumbing, not config — the user only ever sets the boolean.
+
+## Approach
+
+Add a **Docusaurus plugin** alongside the existing remark plugin. The components'
+CSS module is rewritten so each visual property reads a private internal variable
+with a built-in fallback, e.g.
+`box-shadow: var(--gl-card-shadow, none)` and
+`border-color: var(--gl-card-border, var(--ifm-color-emphasis-300))`. The
+fallback values reproduce today's bare look, so with no plugin the cards look
+exactly as they do now.
+
+When the plugin is enabled it injects a single inline `<style>` into `<head>`
+(via `injectHtmlTags`) that **defines those `--gl-card-*` variables on `:root`**
+(plus a `[data-theme='dark']` override). Because the variables cascade from
+`:root`, this works regardless of the components' hashed CSS-module class names —
+no global selector ever needs to know the hashed names. Dark mode rides on
+Docusaurus's existing `data-theme="dark"` attribute.
+
+Rejected alternatives:
+
+- `getClientModules` + a generated CSS file — more build machinery (temp files,
+  ordering) for no gain over an inline tag.
+- Client-side JS setting CSS variables — causes flash-of-unstyled-card and is not
+  SSR-pure; violates the project's static-HTML stance.
+
+## Config
+
+The plugin takes one optional boolean.
+
+```ts
+// docusaurus.config.ts → plugins: []
+[
+  docusaurusGitlabTheme,
+  { theme: true }, // default: true. false → inject nothing.
+]
+```
+
+- `theme: true` (default) → inject the polished card `<style>`.
+- `theme: false` → inject nothing; components fall back to the existing bare
+  CSS-module styling.
+
+Validation: a single optional boolean `theme`. Unknown keys are rejected.
+Invalid config throws at build time with the
+`@ebuildy/docusaurus-plugin-gitlab:` prefix, matching `resolveOptions` in
+`src/options.ts`.
+
+## Light / dark behavior
+
+The injected CSS is theme-aware by construction:
+
+- Cards are styled with Docusaurus's own `--ifm-*` variables
+  (`--ifm-color-primary`, `--ifm-background-surface-color`,
+  `--ifm-color-emphasis-*`), so colors track the active palette.
+- Shadows use `rgb(0 0 0 / α)` so they adapt; a `[data-theme='dark']` block bumps
+  the shadow strength so cards stay legible in dark mode.
+- No hardcoded colors that would fight the active theme.
+
+Toggling the Docusaurus light/dark switch restyles cards automatically, with no
+client JS.
+
+## The theme look (minimal but beautiful)
+
+The injected `<style>` sets the `--gl-card-*` variables to the polished values;
+the CSS module consumes them. Affected class names: `.card`, `.title`, `.muted`,
+`.badge`, `.stats`, `.list`, `.listItem`, `.codeBlock`, etc.
+
+- Card: 1px `--ifm-color-emphasis-200` border, ~10px radius, soft shadow
+  (`0 1px 2px rgb(0 0 0 / .06), 0 2px 8px rgb(0 0 0 / .04)`), surface background.
+- Subtle hover: border shifts toward `--ifm-color-primary`, shadow lifts slightly.
+- Badges: pill shape, `--ifm-color-emphasis-100` background, accent text.
+- Links/title: accent color from `--ifm-color-primary`, weight 600 title.
+- Dark block: stronger shadow alpha, border via `--ifm-color-emphasis-300`.
+
+With `theme: false` the variables are never defined, so the CSS-module fallbacks
+(today's bare look) apply.
+
+## File map
+
+| File | Change |
+|---|---|
+| `src/plugin/index.ts` | New. Plugin factory `docusaurusGitlabTheme(context, options)` implementing `name` + `injectHtmlTags()` → inline `<style>` when `theme !== false`. |
+| `src/plugin/theme.ts` | New. `resolveTheme(input)` (Joi validation + default) and `renderThemeCss()` — pure function returning the `:root { --gl-card-*: … }` + `[data-theme='dark']` CSS string. Separated so it is unit-testable without a Docusaurus context. |
+| `src/components/styles.module.css` | Rewrite visual properties to read `var(--gl-card-*, <current-value>)`, where each fallback equals today's value (so `theme: false` is visually identical to now). No new component classes. |
+| `package.json` | Add `./plugin` to `exports` and a `tsup` entry. |
+| `tsup.config.ts` | Add `src/plugin/index.ts` entry. |
+| `examples/site/docusaurus.config.ts` | Add the plugin to `plugins: []` with `{ theme: true }`. |
+| `test/packaging.test.ts` | Assert the `/plugin` export resolves and stays ESM-only. |
+| `src/gitlab/fetchers.ts` | `fetchProjectInfo`: localize `p.avatar_url` via `ctx.assets.localize` when present. |
+| `src/components/GitlabProjectInfo.tsx` | Render a small rounded avatar `<img>` when `data.avatarUrl` is set. |
+
+## Addition: project avatar in `GitlabProjectInfo`
+
+Independent of the theme, but bundled into this change: show the project's avatar
+in the project-overview card when one exists.
+
+State today: `ProjectInfoData.avatarUrl` already exists and `fetchProjectInfo`
+already maps `p.avatar_url ?? null` — but as the **raw remote URL**, and no
+component renders it. Two gaps to close:
+
+1. **Localize** (build time, no browser token). In `fetchProjectInfo`, when
+   `p.avatar_url` is present, run it through `ctx.assets.localize(avatarUrl, "",
+   project)` and store the returned local served path in `avatarUrl`. The avatar
+   URL is absolute, so `AssetManager.absolute()` passes it through unchanged and
+   the `ref` argument is unused (pass `""`). `requestBinary` carries the token, so
+   private-project avatars work. Failure semantics match README image
+   localization (no special-casing). When `avatar_url` is null, `avatarUrl` stays
+   null and nothing is localized.
+2. **Render** in `GitlabProjectInfo`: when `data.avatarUrl` is set, show a small
+   rounded avatar `<img>` next to the title (with `alt={data.name}` and explicit
+   width/height to avoid layout shift). When null, render the title as today.
+
+No new domain type or fetcher; this reuses `ProjectInfoData`, `fetchProjectInfo`,
+and `AssetManager`.
+
+## Error handling
+
+- Invalid `theme` value → throw at build with the package-prefixed message.
+- `theme: false` → no tag injected; never errors.
+- The plugin does no I/O and no network — `renderThemeCss` is a pure string
+  builder, so there are no runtime failure modes beyond config validation.
+
+## Testing
+
+- `src/plugin/theme.test.ts` — unit tests for `resolveTheme` (default true,
+  explicit false, invalid input throws) and `renderThemeCss` (defines
+  `--gl-card-*` variables on `:root`, references `--ifm-*` for colors, contains a
+  `[data-theme='dark']` block, contains no hardcoded hex palette colors that
+  would override the theme).
+- `src/plugin/index.test.ts` — `injectHtmlTags` returns a head style tag when
+  enabled and nothing when `theme: false`.
+- `test/packaging.test.ts` — `/plugin` subpath export resolves; ESM-only guard
+  still holds.
+- `src/gitlab/fetchers.test.ts` — `fetchProjectInfo` calls `assets.localize` with
+  the avatar URL and returns the localized path; null `avatar_url` skips
+  localization and leaves `avatarUrl` null.
+- `src/components/GitlabProjectInfo.test.tsx` — renders an `img` with the avatar
+  when `avatarUrl` is set; renders no avatar `img` when null.
+- e2e (`test/e2e/build.test.ts`) — example site (now wiring the plugin) builds;
+  run explicitly since it is slow.
+
+Per `CLAUDE.md`: TDD (failing test first), Vitest, `npm run typecheck`.
+
+## Docs
+
+- README: a short "Card theme" section showing the `plugins: []` entry and the
+  boolean.
+- Note that `theme` defaults to `true`.
diff --git a/examples/gitlab/docusaurus.config.ts b/examples/gitlab/docusaurus.config.ts
index 1a5de52..ca92d7c 100644
--- a/examples/gitlab/docusaurus.config.ts
+++ b/examples/gitlab/docusaurus.config.ts
@@ -1,6 +1,9 @@
+import { createRequire } from "node:module";
 import type { Config } from "@docusaurus/types";
 import { remarkGitlab } from "@ebuildy/docusaurus-plugin-gitlab";
 
+const require = createRequire(import.meta.url);
+
 // Live example: embeds REAL public content from gitlab.com.
 // No token is required for these public projects, but you can set GITLAB_TOKEN
 // to raise the API rate limit (unauthenticated is 500 req/min).
@@ -32,7 +35,9 @@ const config: Config = {
           ],
         },
         blog: false,
-        theme: {},
+        theme: {
+          customCss: require.resolve("@ebuildy/docusaurus-plugin-gitlab/theme.css"),
+        },
       },
     ],
   ],
diff --git a/package.json b/package.json
index 12eeaef..7b893d8 100644
--- a/package.json
+++ b/package.json
@@ -25,10 +25,12 @@
       "types": "./dist/components/index.d.ts",
       "import": "./dist/components/index.js",
       "default": "./dist/components/index.js"
-    }
+    },
+    "./theme.css": "./theme.css"
   },
   "files": [
-    "dist"
+    "dist",
+    "theme.css"
   ],
   "scripts": {
     "build": "tsup",
diff --git a/src/components/Fallback.tsx b/src/components/Fallback.tsx
index 5340db5..afa0ab9 100644
--- a/src/components/Fallback.tsx
+++ b/src/components/Fallback.tsx
@@ -1,10 +1,9 @@
 import React from "react";
-import styles from "./styles.module.css";
 import type { FetchError } from "./types.js";
 
 export function Fallback({ error }: { error: FetchError }) {
   return (
-    <div className={styles.fallback} role="alert">
+    <div className="gitlab-fallback" role="alert">
       GitLab data unavailable for <code>{error.project}</code>: {error.message}
     </div>
   );
diff --git a/src/components/GitlabFile.tsx b/src/components/GitlabFile.tsx
index 91f581d..a822b78 100644
--- a/src/components/GitlabFile.tsx
+++ b/src/components/GitlabFile.tsx
@@ -1,21 +1,20 @@
 import { Highlight, themes } from "prism-react-renderer";
 import React from "react";
 import { Fallback } from "./Fallback.js";
-import styles from "./styles.module.css";
 import type { ComponentPayload, FileData } from "./types.js";
 
 export function GitlabFile({ data, error }: ComponentPayload<FileData>) {
   if (error) return <Fallback error={error} />;
   if (!data) return null;
   if (data.kind === "markdown") {
-    return <div className={styles.readme} dangerouslySetInnerHTML={{ __html: data.html }} />;
+    return <div className="gitlab-readme" dangerouslySetInnerHTML={{ __html: data.html }} />;
   }
   return (
-    <div className={styles.codeBlock}>
-      <div className={styles.codeTitle}>{data.path}</div>
+    <div className="gitlab-code">
+      <div className="gitlab-code-title">{data.path}</div>
       <Highlight code={data.code.replace(/\n$/, "")} language={data.language} theme={themes.github}>
         {({ className, style, tokens, getLineProps, getTokenProps }) => (
-          <pre className={`${className} ${styles.codePre}`} style={style}>
+          <pre className={`${className} gitlab-code-pre`} style={style}>
             {tokens.map((line, i) => (
               <div key={i} {...getLineProps({ line })}>
                 {line.map((token, key) => (
diff --git a/src/components/GitlabIssues.tsx b/src/components/GitlabIssues.tsx
index 48326b0..ddb001e 100644
--- a/src/components/GitlabIssues.tsx
+++ b/src/components/GitlabIssues.tsx
@@ -1,21 +1,20 @@
 import React from "react";
 import { Fallback } from "./Fallback.js";
-import styles from "./styles.module.css";
 import type { ComponentPayload, IssueData } from "./types.js";
 
 export function GitlabIssues({ data, error }: ComponentPayload<IssueData[]>) {
   if (error) return <Fallback error={error} />;
   if (!data) return null;
   return (
-    <ul className={styles.list}>
+    <ul className="gitlab-issues">
       {data.map((i) => (
-        <li key={i.iid} className={styles.listItem}>
-          <span className={styles.badge}>{i.state}</span>
-          <a href={i.webUrl}>{i.title}</a>
+        <li key={i.iid} className="gitlab-issue">
+          <span className="gitlab-issue-state" data-state={i.state}>{i.state}</span>
+          <a className="gitlab-issue-title" href={i.webUrl}>{i.title}</a>
           {i.labels.map((l) => (
-            <span key={l} className={styles.badge}>{l}</span>
+            <span key={l} className="gitlab-badge">{l}</span>
           ))}
-          <span className={styles.muted}> · {i.authorName}</span>
+          <span className="gitlab-muted"> · {i.authorName}</span>
         </li>
       ))}
     </ul>
diff --git a/src/components/GitlabProjectInfo.test.tsx b/src/components/GitlabProjectInfo.test.tsx
index 65db413..c9e98c2 100644
--- a/src/components/GitlabProjectInfo.test.tsx
+++ b/src/components/GitlabProjectInfo.test.tsx
@@ -16,8 +16,25 @@ describe("GitlabProjectInfo", () => {
     expect(screen.getByText(/12/)).toBeInTheDocument();
   });
 
+  it("humanizes large star and fork counts", () => {
+    render(<GitlabProjectInfo data={{ ...data, starCount: 6000, forksCount: 1500 } as any} />);
+    expect(screen.getByText(/6k/)).toBeInTheDocument();
+    expect(screen.getByText(/1.5k/)).toBeInTheDocument();
+  });
+
   it("renders the fallback when given an error", () => {
     render(<GitlabProjectInfo error={{ message: "boom", project: "g/r" } as any} />);
     expect(screen.getByRole("alert")).toHaveTextContent("boom");
   });
+
+  it("renders the avatar when avatarUrl is set", () => {
+    render(<GitlabProjectInfo data={{ ...data, avatarUrl: "/gitlab-assets/a.png" } as any} />);
+    const img = screen.getByRole("img", { name: "My Repo" });
+    expect(img).toHaveAttribute("src", "/gitlab-assets/a.png");
+  });
+
+  it("renders no avatar when avatarUrl is null", () => {
+    render(<GitlabProjectInfo data={data as any} />);
+    expect(screen.queryByRole("img")).not.toBeInTheDocument();
+  });
 });
diff --git a/src/components/GitlabProjectInfo.tsx b/src/components/GitlabProjectInfo.tsx
index b44fc29..ed8b375 100644
--- a/src/components/GitlabProjectInfo.tsx
+++ b/src/components/GitlabProjectInfo.tsx
@@ -1,29 +1,40 @@
 import React from "react";
 import { Fallback } from "./Fallback.js";
-import styles from "./styles.module.css";
+import { formatCount } from "./format.js";
 import type { ComponentPayload, ProjectInfoData } from "./types.js";
 
 export function GitlabProjectInfo({ data, error, showStats = true }: ComponentPayload<ProjectInfoData> & { showStats?: boolean }) {
   if (error) return <Fallback error={error} />;
   if (!data) return null;
   return (
-    <div className={styles.card}>
-      <div className={styles.title}>
-        <a href={data.webUrl}>{data.name}</a>
+    <div className="gitlab-card">
+      <div className="gitlab-card-header">
+        {data.avatarUrl && (
+          <img
+            className="gitlab-avatar"
+            src={data.avatarUrl}
+            alt={data.name}
+            width={32}
+            height={32}
+          />
+        )}
+        <div className="gitlab-title">
+          <a href={data.webUrl}>{data.name}</a>
+        </div>
       </div>
-      {data.description && <p className={styles.muted}>{data.description}</p>}
+      {data.description && <p className="gitlab-muted">{data.description}</p>}
       {data.topics.length > 0 && (
         <div>
           {data.topics.map((t) => (
-            <span key={t} className={styles.badge}>{t}</span>
+            <span key={t} className="gitlab-badge">{t}</span>
           ))}
         </div>
       )}
       {showStats && (
-        <div className={styles.stats}>
-          <span>★ {data.starCount}</span>
-          <span>⑂ {data.forksCount}</span>
-          <span className={styles.muted}>updated {new Date(data.lastActivityAt).toLocaleDateString()}</span>
+        <div className="gitlab-stats">
+          <span>★ {formatCount(data.starCount)}</span>
+          <span>⑂ {formatCount(data.forksCount)}</span>
+          <span className="gitlab-muted">updated {new Date(data.lastActivityAt).toLocaleDateString()}</span>
         </div>
       )}
     </div>
diff --git a/src/components/GitlabReadme.tsx b/src/components/GitlabReadme.tsx
index b75aef3..ea32d5c 100644
--- a/src/components/GitlabReadme.tsx
+++ b/src/components/GitlabReadme.tsx
@@ -1,10 +1,9 @@
 import React from "react";
 import { Fallback } from "./Fallback.js";
-import styles from "./styles.module.css";
 import type { ComponentPayload, ReadmeData } from "./types.js";
 
 export function GitlabReadme({ data, error }: ComponentPayload<ReadmeData>) {
   if (error) return <Fallback error={error} />;
   if (!data) return null;
-  return <div className={styles.readme} dangerouslySetInnerHTML={{ __html: data.html }} />;
+  return <div className="gitlab-readme" dangerouslySetInnerHTML={{ __html: data.html }} />;
 }
diff --git a/src/components/GitlabReleases.tsx b/src/components/GitlabReleases.tsx
index 65d7aa0..b73cad2 100644
--- a/src/components/GitlabReleases.tsx
+++ b/src/components/GitlabReleases.tsx
@@ -1,25 +1,24 @@
 import React from "react";
 import { Fallback } from "./Fallback.js";
-import styles from "./styles.module.css";
 import type { ComponentPayload, ReleaseData } from "./types.js";
 
 export function GitlabReleases({ data, error }: ComponentPayload<ReleaseData[]>) {
   if (error) return <Fallback error={error} />;
   if (!data) return null;
   return (
-    <ul className={styles.list}>
+    <ul className="gitlab-releases">
       {data.map((r) => (
-        <li key={r.tagName} className={styles.listItem}>
-          <div className={styles.title}>
+        <li key={r.tagName} className="gitlab-release">
+          <div className="gitlab-title">
             {r.name || r.tagName}
-            {r.tagName !== r.name && <span className={styles.badge}>{r.tagName}</span>}
-            <span className={styles.muted}> · {new Date(r.releasedAt).toLocaleDateString()}</span>
+            {r.tagName !== r.name && <span className="gitlab-badge">{r.tagName}</span>}
+            <span className="gitlab-muted"> · {new Date(r.releasedAt).toLocaleDateString()}</span>
           </div>
-          <div dangerouslySetInnerHTML={{ __html: r.descriptionHtml }} />
+          <div className="gitlab-release-notes" dangerouslySetInnerHTML={{ __html: r.descriptionHtml }} />
           {r.assets.length > 0 && (
-            <div>
+            <div className="gitlab-release-assets">
               {r.assets.map((a) => (
-                <a key={a.url} className={styles.badge} href={a.url}>{a.name}</a>
+                <a key={a.url} className="gitlab-badge" href={a.url}>{a.name}</a>
               ))}
             </div>
           )}
diff --git a/src/components/format.test.ts b/src/components/format.test.ts
new file mode 100644
index 0000000..84eb2ea
--- /dev/null
+++ b/src/components/format.test.ts
@@ -0,0 +1,23 @@
+import { describe, it, expect } from "vitest";
+import { formatCount } from "./format.js";
+
+describe("formatCount", () => {
+  it("leaves counts below 1000 untouched", () => {
+    expect(formatCount(0)).toBe("0");
+    expect(formatCount(12)).toBe("12");
+    expect(formatCount(999)).toBe("999");
+  });
+
+  it("abbreviates thousands with a trailing k", () => {
+    expect(formatCount(1000)).toBe("1k");
+    expect(formatCount(1500)).toBe("1.5k");
+    expect(formatCount(6000)).toBe("6k");
+    expect(formatCount(6200)).toBe("6.2k");
+    expect(formatCount(12500)).toBe("12.5k");
+  });
+
+  it("abbreviates millions with a trailing M", () => {
+    expect(formatCount(1000000)).toBe("1M");
+    expect(formatCount(1500000)).toBe("1.5M");
+  });
+});
diff --git a/src/components/format.ts b/src/components/format.ts
new file mode 100644
index 0000000..603951c
--- /dev/null
+++ b/src/components/format.ts
@@ -0,0 +1,6 @@
+/** Humanize a count GitHub-style: 6000 -> "6k", 6200 -> "6.2k", 1.5e6 -> "1.5M". */
+export function formatCount(n: number): string {
+  if (n < 1000) return String(n);
+  const [value, suffix] = n < 1_000_000 ? [n / 1000, "k"] : [n / 1_000_000, "M"];
+  return `${parseFloat(value.toFixed(1))}${suffix}`;
+}
diff --git a/src/components/styles.module.css b/src/components/styles.module.css
deleted file mode 100644
index 22dbaa5..0000000
--- a/src/components/styles.module.css
+++ /dev/null
@@ -1,47 +0,0 @@
-.card {
-  border: 1px solid var(--ifm-color-emphasis-300);
-  border-radius: var(--ifm-card-border-radius, 8px);
-  padding: 1rem;
-  margin: 1rem 0;
-  background: var(--ifm-card-background-color, var(--ifm-background-surface-color));
-}
-.title { font-weight: 600; }
-.muted { color: var(--ifm-color-emphasis-600); }
-.stats { display: flex; gap: 1rem; margin-top: 0.5rem; }
-.badge {
-  display: inline-block;
-  padding: 0 0.5rem;
-  border-radius: 4px;
-  background: var(--ifm-color-emphasis-200);
-  font-size: 0.85em;
-  margin-right: 0.25rem;
-}
-.fallback {
-  border-left: 4px solid var(--ifm-color-warning);
-  padding: 0.75rem 1rem;
-  background: var(--ifm-color-warning-contrast-background);
-  margin: 1rem 0;
-}
-.list { list-style: none; padding: 0; margin: 1rem 0; }
-.listItem { padding: 0.5rem 0; border-bottom: 1px solid var(--ifm-color-emphasis-200); }
-.readme :global(img) { max-width: 100%; }
-.codeBlock {
-  margin: 1rem 0;
-  border: 1px solid var(--ifm-color-emphasis-300);
-  border-radius: var(--ifm-code-border-radius, 6px);
-  overflow: hidden;
-}
-.codeTitle {
-  padding: 0.4rem 1rem;
-  font-size: 0.85em;
-  font-family: var(--ifm-font-family-monospace);
-  color: var(--ifm-color-emphasis-700);
-  background: var(--ifm-color-emphasis-100);
-  border-bottom: 1px solid var(--ifm-color-emphasis-300);
-}
-.codePre {
-  margin: 0;
-  padding: 1rem;
-  overflow: auto;
-  font-size: var(--ifm-code-font-size, 90%);
-}
diff --git a/src/css.d.ts b/src/css.d.ts
deleted file mode 100644
index 96ac9c7..0000000
--- a/src/css.d.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-declare module "*.module.css" {
-  const classes: { readonly [key: string]: string };
-  export default classes;
-}
diff --git a/src/gitlab/fetchers.test.ts b/src/gitlab/fetchers.test.ts
index 49538e0..390e3c4 100644
--- a/src/gitlab/fetchers.test.ts
+++ b/src/gitlab/fetchers.test.ts
@@ -23,10 +23,27 @@ describe("fetchProjectInfo", () => {
         star_count: 3, forks_count: 1, topics: ["x"], last_activity_at: "2026-01-01T00:00:00Z", avatar_url: null,
       })),
     };
-    const data = await fetchProjectInfo(ctx(client), { project: "g/r" });
+    const c = ctx(client);
+    const data = await fetchProjectInfo(c, { project: "g/r" });
     expect(data).toMatchObject({ id: 7, path: "g/r", starCount: 3, topics: ["x"] });
+    expect(data.avatarUrl).toBeNull();
+    expect(c.assets.localize).not.toHaveBeenCalled();
     expect(client.getProject).toHaveBeenCalledWith("g/r");
   });
+
+  it("localizes the avatar when the project has one", async () => {
+    const client = {
+      getProject: vi.fn(async () => ({
+        id: 7, path_with_namespace: "g/r", name: "r", description: "d", web_url: "https://gitlab.com/g/r",
+        star_count: 3, forks_count: 1, topics: ["x"], last_activity_at: "2026-01-01T00:00:00Z",
+        avatar_url: "https://gitlab.com/uploads/avatar.png",
+      })),
+    };
+    const c = ctx(client);
+    const data = await fetchProjectInfo(c, { project: "g/r" });
+    expect(c.assets.localize).toHaveBeenCalledWith("https://gitlab.com/uploads/avatar.png", "", "g/r");
+    expect(data.avatarUrl).toBe("/gitlab-assets/httpsgitlabcomuploadsavatarpng.png");
+  });
 });
 
 describe("fetchReleases", () => {
diff --git a/src/gitlab/fetchers.ts b/src/gitlab/fetchers.ts
index 76dcc34..c20e3fc 100644
--- a/src/gitlab/fetchers.ts
+++ b/src/gitlab/fetchers.ts
@@ -31,6 +31,9 @@ export async function fetchProjectInfo(ctx: GitLabContext, attrs: Attrs): Promis
   const project = String(attrs.project);
   return memo(ctx, `projectInfo:${project}`, async () => {
     const p = await ctx.client.getProject(attrs.project as string | number);
+    const avatarUrl = p.avatar_url
+      ? await ctx.assets.localize(p.avatar_url, "", project)
+      : null;
     return {
       id: p.id,
       path: p.path_with_namespace,
@@ -41,7 +44,7 @@ export async function fetchProjectInfo(ctx: GitLabContext, attrs: Attrs): Promis
       forksCount: p.forks_count,
       topics: p.topics ?? [],
       lastActivityAt: p.last_activity_at,
-      avatarUrl: p.avatar_url ?? null,
+      avatarUrl,
     } satisfies ProjectInfoData;
   }).then((v) => ({ ...v, path: v.path || project }));
 }
diff --git a/theme.css b/theme.css
new file mode 100644
index 0000000..40ff140
--- /dev/null
+++ b/theme.css
@@ -0,0 +1,218 @@
+/*
+ * @ebuildy/docusaurus-plugin-gitlab — optional card theme.
+ *
+ * Minimal, light/dark-aware styling for the <Gitlab*> components. It uses
+ * Infima (Docusaurus) CSS variables, so it tracks your site's active theme
+ * automatically. Apply it by adding this file to your preset's
+ * `theme.customCss`, or copy it into your own stylesheet and tweak freely.
+ */
+
+/* Project overview card */
+.gitlab-card {
+  border: 1px solid var(--ifm-color-emphasis-200);
+  border-radius: 10px;
+  padding: 1rem;
+  margin: 1rem 0;
+  background: var(--ifm-background-surface-color);
+  box-shadow: 0 1px 2px rgb(0 0 0 / 0.06), 0 2px 8px rgb(0 0 0 / 0.04);
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+.gitlab-card:hover {
+  border-color: var(--ifm-color-primary);
+}
+.gitlab-card-header {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+}
+.gitlab-avatar {
+  width: 32px;
+  height: 32px;
+  border-radius: 8px;
+  object-fit: cover;
+  flex: none;
+}
+.gitlab-title {
+  font-weight: 600;
+}
+.gitlab-title a {
+  color: var(--ifm-color-primary);
+}
+.gitlab-muted {
+  color: var(--ifm-color-emphasis-600);
+}
+.gitlab-stats {
+  display: flex;
+  gap: 1rem;
+  margin-top: 0.5rem;
+}
+
+/* Badges: topics, tags, labels, release assets */
+.gitlab-badge {
+  display: inline-block;
+  padding: 0 0.5rem;
+  margin-right: 0.25rem;
+  border-radius: 999px;
+  background: var(--ifm-color-emphasis-100);
+  color: var(--ifm-color-primary);
+  font-size: 0.85em;
+}
+
+/* Issues list */
+.gitlab-issues {
+  list-style: none;
+  padding: 0;
+  margin: 1rem 0;
+}
+.gitlab-issue {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.4rem;
+  padding: 0.6rem 0;
+  border-bottom: 1px solid var(--ifm-color-emphasis-200);
+}
+.gitlab-issue:last-child {
+  border-bottom: 0;
+}
+.gitlab-issue-title {
+  font-weight: 500;
+}
+.gitlab-issue-state {
+  display: inline-block;
+  padding: 0 0.5rem;
+  border-radius: 999px;
+  font-size: 0.8em;
+  font-weight: 600;
+  text-transform: capitalize;
+  color: #fff;
+  background: var(--ifm-color-emphasis-500);
+}
+.gitlab-issue-state[data-state="opened"] {
+  background: var(--ifm-color-success);
+}
+.gitlab-issue-state[data-state="closed"] {
+  background: var(--ifm-color-danger);
+}
+
+/* Releases: a vertical timeline of release cards */
+.gitlab-releases {
+  position: relative;
+  list-style: none;
+  margin: 1.5rem 0;
+  padding: 0 0 0 28px;
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+}
+/* the timeline rail */
+.gitlab-releases::before {
+  content: "";
+  position: absolute;
+  top: 6px;
+  bottom: 6px;
+  left: 6px;
+  width: 2px;
+  border-radius: 1px;
+  background: linear-gradient(to bottom, var(--ifm-color-primary), var(--ifm-color-emphasis-300));
+}
+.gitlab-release {
+  position: relative;
+  border: 1px solid var(--ifm-color-emphasis-200);
+  border-radius: 10px;
+  padding: 1rem 1.25rem;
+  background: var(--ifm-background-surface-color);
+  box-shadow: 0 1px 2px rgb(0 0 0 / 0.06), 0 2px 8px rgb(0 0 0 / 0.04);
+  transition: border-color 0.15s ease, box-shadow 0.15s ease, transform 0.15s ease;
+}
+.gitlab-release:hover {
+  border-color: var(--ifm-color-primary);
+  transform: translateX(2px);
+}
+/* the node sitting on the rail */
+.gitlab-release::before {
+  content: "";
+  position: absolute;
+  top: 18px;
+  left: -28px;
+  width: 14px;
+  height: 14px;
+  border-radius: 50%;
+  background: var(--ifm-color-primary);
+  border: 2px solid var(--ifm-background-surface-color);
+  box-shadow: 0 0 0 2px var(--ifm-color-primary);
+}
+/* the connector from the rail to the card */
+.gitlab-release::after {
+  content: "";
+  position: absolute;
+  top: 24px;
+  left: -14px;
+  width: 14px;
+  height: 2px;
+  background: var(--ifm-color-emphasis-300);
+}
+/* make the latest release pop */
+.gitlab-release:first-child::before {
+  box-shadow: 0 0 0 2px var(--ifm-color-primary), 0 0 9px 1px var(--ifm-color-primary);
+}
+.gitlab-release-notes {
+  margin-top: 0.5rem;
+  color: var(--ifm-color-emphasis-800);
+}
+.gitlab-release-notes > :first-child {
+  margin-top: 0;
+}
+.gitlab-release-notes > :last-child {
+  margin-bottom: 0;
+}
+.gitlab-release-notes img {
+  max-width: 100%;
+}
+.gitlab-release-assets {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.4rem;
+  margin-top: 0.75rem;
+}
+
+/* README / markdown file embed */
+.gitlab-readme img {
+  max-width: 100%;
+}
+
+/* Error fallback */
+.gitlab-fallback {
+  border-left: 4px solid var(--ifm-color-warning);
+  padding: 0.75rem 1rem;
+  margin: 1rem 0;
+  background: var(--ifm-color-warning-contrast-background);
+}
+
+/* Code file embed */
+.gitlab-code {
+  margin: 1rem 0;
+  border: 1px solid var(--ifm-color-emphasis-200);
+  border-radius: 8px;
+  overflow: hidden;
+}
+.gitlab-code-title {
+  padding: 0.4rem 1rem;
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.85em;
+  color: var(--ifm-color-emphasis-700);
+  background: var(--ifm-color-emphasis-100);
+  border-bottom: 1px solid var(--ifm-color-emphasis-200);
+}
+.gitlab-code-pre {
+  margin: 0;
+  padding: 1rem;
+  overflow: auto;
+  font-size: var(--ifm-code-font-size, 90%);
+}
+
+/* Slightly stronger shadows so cards stay legible in dark mode */
+[data-theme='dark'] .gitlab-card,
+[data-theme='dark'] .gitlab-release {
+  box-shadow: 0 1px 2px rgb(0 0 0 / 0.3), 0 2px 10px rgb(0 0 0 / 0.25);
+}