feat: unify site typography and article layout

.github/workflows/validate.yml

@@ -20,8 +20,14 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      - name: Lint
-        run: bun run lint
+      - name: Format check
+        run: bun run format:check
+
+      - name: Lint (Oxlint, better-tailwindcss, shadcn)
+        run: bun run lint:ox
+
+      - name: Unused code and dependencies (Knip)
+        run: bun run lint:unused
 
       - name: Typst format check
         run: bun run format:typ:check

knip.jsonc

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/knip@6/schema-jsonc.json",
+  // Articles are loaded by path at runtime; scripts are standalone entry points.
+  "entry": ["src/content/blog/**/page.mdx", "scripts/*.ts"],
+  "ignoreIssues": {
+    // Retain the upstream API of used registry components, but detect unused files.
+    "src/components/ui/**": ["exports", "types"],
+  },
+  // Loaded via createRequire(import.meta.url); ships a native Typst executable.
+  "ignoreDependencies": ["@flukxr/typst-cli"],
+  // Installed and pinned by mise, not npm.
+  "ignoreBinaries": ["typstyle"],
+  "ignoreExportsUsedInFile": true,
+}

next.config.ts

@@ -21,6 +21,9 @@ const nextConfig: NextConfig = {
         ]
       : [],
   experimental: {
+    // Reused compiler output has served stale Tailwind theme values.
+    turbopackFileSystemCacheForBuild: false,
+    turbopackFileSystemCacheForDev: false,
     useTypeScriptCli: true,
   },
   images: {
@@ -48,7 +51,6 @@ const nextConfig: NextConfig = {
   outputFileTracingIncludes: {
     "/": blogSourceFiles,
     "/writing/[slug]": blogImageFiles,
-    "/writing/[slug]/markdown": blogSourceFiles,
     "/writing/[slug]/opengraph-image": blogImageFiles,
     "/writing/[slug]/share-image": blogImageFiles,
     "/writing/[slug]/twitter-image": blogImageFiles,
@@ -70,12 +72,6 @@ const nextConfig: NextConfig = {
     },
     { source: "/resume", destination: "/journey", permanent: true },
   ],
-  rewrites: async () => [
-    {
-      destination: "/writing/:slug/markdown",
-      source: "/writing/:slug.md",
-    },
-  ],
 };
 
 const remarkStaticImageImports = new URL(
@@ -89,6 +85,11 @@ const remarkEmbedGitHub = new URL(
   import.meta.url
 ).pathname;
 
+const rehypeArticleGrid = new URL(
+  "src/lib/rehype-article-grid.mjs",
+  import.meta.url
+).pathname;
+
 const withMDX = createMDX({
   options: {
     rehypePlugins: [
@@ -115,6 +116,7 @@ const withMDX = createMDX({
           keepBackground: false,
         },
       ],
+      rehypeArticleGrid,
     ],
     remarkPlugins: [
       remarkStaticImageImports,

oxfmt.config.ts

@@ -6,6 +6,8 @@ export default defineConfig({
   // Preserve authored and historical code samples exactly as published.
   embeddedLanguageFormatting: "off",
   ignorePatterns: [
+    // Keep registry-generated shadcn sources unchanged.
+    "src/components/ui/**",
     ...(ultracite.ignorePatterns ?? []),
     "**/.rulesync",
     "**/.rulesync/**",

oxlint.config.ts

@@ -1,10 +1,15 @@
+import { getDefaultSelectors } from "eslint-plugin-better-tailwindcss/api/defaults";
 import { defineConfig } from "oxlint";
 import type { OxlintConfig } from "oxlint";
 import core from "ultracite/oxlint/core";
 import next from "ultracite/oxlint/next";
 import react from "ultracite/oxlint/react";
 
 const compatibilityRules = {
+  // Preserve the existing lint policy when upgrading Oxlint for JS plugins.
+  "max-classes-per-file": "off",
+  "react/set-state-in-effect": "off",
+  "unicorn/consistent-function-scoping": "off",
   "func-style": "off",
   "jsx-a11y/prefer-tag-over-role": "off",
   "nextjs/no-assign-module-variable": "off",
@@ -33,7 +38,19 @@ const compatibilityRules = {
 
 export default defineConfig({
   extends: [core, react, next],
+  jsPlugins: ["eslint-plugin-better-tailwindcss", "@shadcn/lint"],
+  settings: {
+    "better-tailwindcss": {
+      entryPoint: "src/app/globals.css",
+      selectors: [
+        ...getDefaultSelectors(),
+        { kind: "variable", name: "ClassNames?$", match: [{ type: "string" }] },
+      ],
+    },
+  },
   ignorePatterns: [
+    // Keep registry-generated shadcn sources unchanged.
+    "src/components/ui/**",
     ...(core.ignorePatterns ?? []),
     "**/.rulesync",
     "**/.rulesync/**",
@@ -42,6 +59,57 @@ export default defineConfig({
     "**/tsconfig.tsbuildinfo",
   ],
   overrides: [
+    {
+      files: ["src/**/*.{ts,tsx,js,jsx}"],
+      rules: {
+        "better-tailwindcss/no-duplicate-classes": "error",
+        "better-tailwindcss/no-unnecessary-whitespace": "error",
+        "better-tailwindcss/no-deprecated-classes": "error",
+        "better-tailwindcss/no-conflicting-classes": "error",
+        "better-tailwindcss/no-concatenated-classes": "error",
+        "better-tailwindcss/enforce-shorthand-classes": "error",
+        "better-tailwindcss/enforce-canonical-classes": "error",
+        "better-tailwindcss/no-restricted-classes": [
+          "error",
+          {
+            restrict: [
+              {
+                pattern: "(?:^|:)transition-all$",
+                message:
+                  "Name the properties that animate; avoid animating layout accidentally.",
+              },
+              {
+                pattern:
+                  "(?:^|:)duration-(?!0$|\\(--motion-(?:fast|layout|exit)\\)$).+",
+                message:
+                  "Use duration-(--motion-fast), duration-(--motion-layout), or duration-(--motion-exit).",
+              },
+              {
+                pattern: "(?:^|:)\\[transition(?:-duration)?:",
+                message:
+                  "Use transition utilities with motion tokens, or the shared motion selectors in site.css.",
+              },
+            ],
+          },
+        ],
+        // shadcn also recognizes plain CSS selectors in the theme imports.
+        "shadcn/no-unknown-classes": [
+          "error",
+          {
+            // Structural hooks referenced by arbitrary selectors and the MDX transform.
+            allow: [
+              "github-code-embed",
+              "journey",
+              "site-nav-link",
+              "site-row",
+              "site-row-meta",
+              "site-text-link",
+            ],
+          },
+        ],
+        "shadcn/no-raw-colors": "error",
+      },
+    },
     {
       files: ["src/lib/*.mjs"],
       rules: {

package.json

@@ -9,7 +9,7 @@
     "start": "next start",
     "test": "bun test ./tests",
     "typecheck": "tsgo --noEmit",
-    "lint": "ultracite check && oxlint .",
+    "lint": "ultracite check && bun run lint:unused",
     "lint:ox": "oxlint .",
     "rulesync": "bunx rulesync generate",
     "format": "ultracite fix",
@@ -24,7 +24,8 @@
     "codex:account": "bun scripts/configure-codex-account.ts",
     "github:sync": "bun scripts/sync-github-commits.ts",
     "github:verify": "bun scripts/verify-github-work-units.ts",
-    "supabase:cron": "bun scripts/configure-supabase-cron.ts"
+    "supabase:cron": "bun scripts/configure-supabase-cron.ts",
+    "lint:unused": "knip"
   },
   "dependencies": {
     "@ai-sdk/openai": "4.0.41",
@@ -35,11 +36,10 @@
     "@next/mdx": "16.3.4",
     "@remark-embedder/core": "3.0.3",
     "@t3-oss/env-nextjs": "0.13.11",
-    "@tailwindcss/typography": "0.5.20",
     "@tanstack/react-query": "5.102.8",
     "ai": "7.0.63",
     "class-variance-authority": "0.7.1",
-    "clsx": "2.1.1",
+    "cn": "0.4.0",
     "drizzle-orm": "0.45.2",
     "feed": "5.2.1",
     "gpt-tokenizer": "4.0.0",
@@ -62,12 +62,13 @@
     "shadcn": "4.11.0",
     "shiki": "4.4.3",
     "sonner": "2.0.8",
-    "tailwind-merge": "3.6.0",
     "unist-util-visit": "5.1.0",
     "zod": "4.4.3"
   },
   "devDependencies": {
     "@flukxr/typst-cli": "0.15.0-npm.2",
+    "@mdx-js/mdx": "3.1.1",
+    "@shadcn/lint": "0.2.0",
     "@tailwindcss/postcss": "4.3.1",
     "@types/bun": "1.4.1",
     "@types/mdx": "2.0.14",
@@ -77,8 +78,10 @@
     "@typescript/native-preview": "7.0.0-dev.20260624.1",
     "babel-plugin-react-compiler": "1.0.0",
     "drizzle-kit": "0.31.10",
+    "eslint-plugin-better-tailwindcss": "4.7.0",
+    "knip": "6.38.0",
     "oxfmt": "0.56.0",
-    "oxlint": "1.71.0",
+    "oxlint": "1.85.0",
     "oxlint-tsgolint": "0.23.0",
     "schema-dts": "2.0.0",
     "sharp": "0.35.4",

src/app/(blog)/writing/[slug]/page.tsx

@@ -5,12 +5,10 @@ import type { ComponentType } from "react";
 
 import { ArticleAnalytics } from "@/components/blog/article-analytics";
 import { ArticleProse } from "@/components/blog/article-prose";
-import { BlogPostActions } from "@/components/blog/blog-post-actions";
 import { JsonLd } from "@/components/json-ld";
 import MDXImage from "@/components/mdx/MDXImage";
 import { SiteMain } from "@/components/site-page";
 import { SiteShell } from "@/components/site-shell";
-import { Separator } from "@/components/ui/separator";
 import { siteNavigation } from "@/content/site";
 import { buildAskAiPrompt } from "@/lib/ask-ai";
 import {
@@ -84,27 +82,19 @@ export default async function BlogPostPage({ params }: { params: PageParams }) {
         title: metadata.title,
         prompt: buildAskAiPrompt({
           title: metadata.title,
-          sourceUrl: publicUrl(`/writing/${slug}.md`),
+          sourceUrl: publicUrl(`/writing/${slug}`),
         }),
       }}
     >
-      <SiteMain className="relative">
+      <SiteMain className="article-main relative @container/article">
         <JsonLd data={jsonLd} />
-        <article className="flex flex-col gap-8">
-          <header className="flex flex-col">
-            <h1 className="section-title mb-4 font-serif text-2xl font-normal text-foreground text-balance">
-              {metadata.title}
-            </h1>
-            <div
-              className="flex items-center justify-between gap-3 border-y border-border whitespace-nowrap"
-              data-slot="blog-post-rail"
-            >
-              <div className="flex min-h-11 shrink-0 items-center gap-2 text-xs text-muted-foreground sm:gap-3">
-                <time dateTime={date.toISOString()}>{formatDate(date)}</time>
-                <Separator orientation="vertical" />
-                <span>{readingTime}</span>
-              </div>
-              <BlogPostActions markdownHref={`/writing/${slug}.md`} />
+        <article className="article-layout">
+          <header className="article-header">
+            <h1 className="article-title">{metadata.title}</h1>
+            <div className="article-meta flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground">
+              <time dateTime={date.toISOString()}>{formatDate(date)}</time>
+              <span aria-hidden="true">·</span>
+              <span>{readingTime}</span>
             </div>
           </header>
           <ArticleAnalytics slug={slug} />

src/app/(blog)/writing/page.tsx

@@ -20,7 +20,7 @@ export default async function BlogIndexPage() {
       askAiContext={{
         label: "My writing",
         title: `${siteConfig.name}’s writing`,
-        prompt: `Read ${publicUrl("/llms.txt")} and ${publicUrl(pages.writing.path)}. Help me explore ${siteConfig.name}’s published articles. Recommend an article to start with, then answer my questions using the linked Markdown posts as sources. Cite the articles you use and say if you cannot access them.`,
+        prompt: `Read ${publicUrl("/llms.txt")} and ${publicUrl(pages.writing.path)}. Help me explore ${siteConfig.name}’s published articles. Recommend an article to start with, then answer my questions using the linked articles as sources. Cite the articles you use and say if you cannot access them.`,
       }}
     >
       <JsonLd data={buildBlogCollectionJsonLd(posts)} />