minimal-portfolio

Imported from jonasbergmar/minimal-portfolio (AGENTS.md). Install upstream with npx skills add jonasbergmar/minimal-portfolio. Copyright stays with the author.

Agent rules — Astro + Sanity starter

This file is the contract for anyone (human or agent) changing this repo. Follow it exactly. Where it is silent, pick the simplest option that matches existing conventions. Do not add features that are not requested.

Human setup lives in README.md. This file is for how to change the system.

Sanity best practices (mandatory)

Before changing schema, GROQ, TypeGen, Presentation, Visual Editing, images, Portable Text, Studio structure, or the Astro integration: load the matching Sanity skill rules (astro, visual-editing, schema, groq, typegen, page-builder, project-structure, …) and verify against current docs for the installed package versions. Prefer official @sanity/astro / Studio APIs over custom workarounds. Do not invent env vars, loaders, or stega handling that contradict those guides.

Structure note: Sanity prefers a standalone Studio in studio/ (TypeGen, CLI, optional sanity deploy). This template also embeds Studio at /admin via studioBasePath because that is a product requirement — keep schema/CLI in studio/, re-export config into web/, and do not move the source of truth into the Astro app.

Goal

A cloneable template. After clone: create a Sanity project, copy .env.example → .env, npm i, allow CORS for http://localhost:4321, npm run seed, then npm run dev. That yields the Astro site on http://localhost:4321, Studio on http://localhost:4321/admin, sample content, visual editing (Presentation + overlays), and a hidden /styleguide brandbook. Human setup details live in README.md; sample documents live in studio/seed/starter.ndjson.

Stack

• Astro 5 — output: 'static'. Drafts render on demand in astro dev.
• Sanity Studio v4 — schema and CLI live in studio/. Embedded in Astro at /admin via @sanity/astro (studioBasePath). Use studioRouterHistory: 'browser' so Presentation intent links (/admin/intent/edit/…) resolve; hash history only serves /admin and 404s those paths. Dev SPA fallback rewrites /admin/* → /admin; static hosts need the same rewrite in production. web/sanity.config.ts re-exports studio/sanity.config.ts. Optional standalone: npm run dev -w studio (port 3333) or npm run deploy -w studio.
• Tailwind CSS v4 via @tailwindcss/vite. CSS-first. No tailwind.config.js. Theme values come from CSS variables mapped through @theme.
• Lenis + GSAP (ScrollTrigger) for scroll; CSS for hover/focus/accordion.
• TypeScript everywhere, strict.
• Prettier with prettier-plugin-astro and prettier-plugin-tailwindcss.
• npm workspaces (web, studio). One root npm i.

Layout

├── package.json              # workspaces: ["web", "studio"]; scripts: dev, build, typegen, format
├── .env.example              # single env file at root, shared by both apps
├── AGENTS.md
├── README.md
├── studio/
│   ├── sanity.config.ts      # Studio config (schema, structure, Presentation)
│   ├── sanity.cli.ts         # TypeGen: scan ../web/src, emit ../web/src/sanity.types.ts
│   └── src/
│       ├── schemaTypes/
│       │   ├── documents/    # page, homePage, faq, siteSettings
│       │   ├── objects/      # seo, link, blockContent, pageBuilder
│       │   ├── blocks/       # hero, features, splitImage, faqs, callToAction
│       │   └── index.ts
│       ├── structure/        # desk structure, singletons
│       └── presentation/     # document location resolvers
└── web/
    ├── astro.config.mjs      # envDir = repo root; sanity (studioBasePath /admin) + react + tailwind
    ├── sanity.config.ts      # re-exports ../studio/sanity.config.ts for the embedded Studio
    └── src/
        ├── styles/
        │   ├── tokens.css    # ALL design variables live here
        │   └── global.css    # fluid rem + reset + tailwind + @theme + base + shared classes
        ├── lib/              # load-query, queries, image, links, animations, lenis
        ├── layouts/Layout.astro
        ├── components/
        │   ├── blocks/       # full-width page-builder sections only
        │   ├── layout/       # site chrome
        │   └── ui/           # small reusable primitives
        └── pages/            # index.astro, [...slug].astro, styleguide.astro

Never mix component folders. blocks/ = page-builder sections. layout/ = navbar/footer/skip link. ui/ = Button, Eyebrow, Heading, SanityImage, RichText.

Environment

Root .env only. Astro reads it via envDir + Vite loadEnv pointed at the repo root. Studio CLI (sanity.cli.ts) loads the same file with dotenv and injects PUBLIC_ / SANITY_STUDIO_ into the standalone Vite config. Embedded Studio gets the same values through astro.config.mjs vite.define.

Required keys (see .env.example):

• PUBLIC_SANITY_PROJECT_ID
• PUBLIC_SANITY_DATASET
• PUBLIC_SANITY_VISUAL_EDITING_ENABLED
• PUBLIC_SANITY_STUDIO_URL
• SANITY_API_READ_TOKEN
• SANITY_STUDIO_PREVIEW_ORIGIN

Do not invent extra env vars unless a task requires them.

Sizing — rem only, fluid root

Every size is rem (font, spacing, widths, radii). Exceptions: breakpoints in media queries may be px; borders may be 1px hairlines. Nothing else in px.

The fluid root snippet at the top of web/src/styles/global.css is sacred — do not retune, replace, or wrap it in clamp(). Tokens stay plain rem because the root scales. Body text ≈ 1.6rem (--text-md). Repeated values become tokens. No magic numbers in components.

global.css order: (1) fluid root snippet, (2) Andy Bell–style reset including prefers-reduced-motion, (3) @import "tailwindcss", (4) @theme inline { … } mapping tokens, (5) base elements, (6) .container, .eyebrow, .prose.

Design tokens

web/src/styles/tokens.css is the only place to retune look and feel. Map tokens into Tailwind in @theme inline so bg-accent, text-ink-muted, rounded-md, p-8, font-display resolve to the same variables. Components may use utilities or var(--…).

Do not add styles on /styleguide (or anywhere) that are not derived from tokens.

Animation

• Init Lenis once in Layout via lib/lenis.ts. Sync: lenis.on('scroll', ScrollTrigger.update); drive Lenis from gsap.ticker with lagSmoothing(0).
• Reveals are declarative in lib/animations.ts: data-animate="fade-up" | "fade-in"; data-animate="stagger" + children data-animate-child. Blocks opt in — no per-component GSAP except special cases (styleguide cover / replay).
• CSS handles hover, focus, accordion using motion tokens.
• Reduced motion: do not init Lenis; gsap.set final state.
• No-JS / a11y: content must be visible before JS. Animate from a hidden state applied by JS. Never hide content in CSS pending animation.

Data layer & visual editing

• Fetch only through loadQuery (web/src/lib/load-query.ts), including getStaticPaths.
• When PUBLIC_SANITY_VISUAL_EDITING_ENABLED === 'true': perspective drafts, stega: true, resultSourceMap: 'withKeyArraySelector', token required (throw if missing), useCdn: false. Otherwise: published, no stega.
• Layout.astro renders <VisualEditing /> from @sanity/astro/visual-editing gated by the flag.
• Queries: defineQuery from groq in lib/queries.ts. Shared fragments for images, links, SEO, and page-builder. Always project _key and _type on arrays. Expand FAQ refs with faqs[]->.
• TypeGen: studio/sanity.cli.ts scans ../web/src/**, emits ../web/src/sanity.types.ts. After schema or query changes: npm run typegen. Type blocks with Extract<…, { _type: 'hero' }> from query result types.
• Queries used by getStaticPaths must be imported from lib/ (Astro hoists getStaticPaths; module-scope consts in the same .astro file are not visible inside it). TypeGen does not reliably parse .astro frontmatter — keep queries in .ts.

Stega golden rule

Sanity content model

• Always defineType / defineField / defineArrayMember.
• Icons from @sanity/icons on every document/object (root named exports in Studio v4).
• Model data, not presentation: no color, fontSize, or heading-level fields. Heading levels are decided in the frontend (Heading as prop).
• Every block preview: title, block name as subtitle, image/icon media.
• Image alt is required on schema images.
• Documents: page (title, slug, content pageBuilder, seo), homePage singleton, privacyPolicy singleton (title, lastUpdated, blockContent body, seo → /privacy), article (title, slug, excerpt, publishedAt, image, body, seo → /articles/[slug]), caseStudy (title, slug, client, summary, publishedAt, image, body, seo → /case-studies/[slug]), faq (question, blockContent answer), testimonial (quote, name, role, company, image), siteSettings singleton (siteTitle, nav links, footerText).
• Objects: seo, link (label + internal/external radio; internal refs: page, homePage, privacyPolicy, article, caseStudy), blockContent (normal/h2/h3/quote, bullet/number, strong/em/code, link annotation, captioned image), pageBuilder (blocks, insertMenu grid → /static/block-previews/<type>.png).
• Blocks: hero, features, splitImage, faqs (heading + FAQ refs), testimonials (heading + testimonial refs), callToAction.
• Structure: singletons pinned via S.document().documentId(...) with IDs homePage / siteSettings / privacyPolicy. Then Pages, Articles, Case studies, Testimonials, FAQs; remaining types filtered.
• Presentation: previewUrl.origin from SANITY_STUDIO_PREVIEW_ORIGIN (site origin). Locations: homePage → /, page → /${slug}, privacyPolicy → /privacy, article → /articles/${slug}, caseStudy → /case-studies/${slug}.
• Reserved slug: skip admin, privacy, articles, case-studies, styleguide in page getStaticPaths. Never let [...slug] own /admin/*.
• Edit intents: Visual Editing opens /admin/intent/edit/mode=presentation;id=…;type=…;path=…. That requires browser history + /admin/* → Studio SPA rewrite.

Adding a block (4 steps, this order)

1. Schema in studio/src/schemaTypes/blocks/ — icon + preview, register in index.ts and pageBuilder.
2. Query fragment in web/src/lib/queries.ts — _key, _type, expand refs if shared.
3. Component in web/src/components/blocks/ — Extract<…, { _type: '…' }>.
4. Registry in PageBuilder.astro. Unknown types: dev warning only, nothing in production.

Then npm run typegen.

Components

• Button — <a> if href is present, else <button type="button">. Variants primary | secondary, sizes sm | md. External http(s) to another origin: rel="noopener noreferrer". Disabled links: inert <span aria-disabled="true">. Disabled buttons: native disabled. Focus ring and hover from tokens.
• Navbar — title + links from Site Settings. Real <button> toggle with aria-expanded / aria-controls. Escape closes and returns focus. Current page: aria-current="page". Sticky, height --navbar-height.
• Footer — nav + footer text + copyright year.
• SkipLink — first focusable, jumps to #main.
• Heading — as for semantic level. Never store heading level in Sanity.
• SanityImage — @sanity/image-url, alt from schema, width/height, lazy by default.
• RichText — astro-portabletext wrapped in .prose.
• PageBuilder — _type → component from one registry. Always use _key (never array index as a key).

Accessibility (non-negotiable)

Before building or changing any UI (web/src/components, layouts, pages, styles that affect interaction): load the web-design-guidelines skill and apply its accessibility and focus rules as mandatory best practice. Fetch the latest checklist from https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md when reviewing or shipping UI — do not rely on memory. Prefer semantic HTML over ARIA; never ship icon-only controls without aria-label, interactive elements without keyboard support / visible :focus-visible, or motion that ignores prefers-reduced-motion.

Repo baseline (always keep): semantic landmarks (header, nav, main id="main", footer); exactly one h1 per page; required image alts; :focus-visible from tokens on interactives; FAQ accordion as <details>/<summary>; color tokens meet WCAG AA; keyboard-test navbar and FAQ; honor prefers-reduced-motion globally.

/styleguide

Hidden brandbook: <meta name="robots" content="noindex">, linked from nowhere, not in any sitemap. Cover + numbered chapters 01–07 (foundations, color, type, spacing, motion, components, blocks). Sticky chapter nav + scroll-spy on desktop. One h1 on the cover. Mono token labels. Specimen cards from surface/line/radius tokens. Replayable GSAP demos. Built entirely from tokens and existing components.

Prettier & checks

Root .prettierrc: no semicolons, single quotes, both plugins. npm run format. Ignore generated files (sanity.types.ts, dist, .astro). After web or studio changes: npm run check -w web and npx tsc --noEmit in studio. Fix until clean.

Do not

• Hide content in CSS pending animation.
• Store presentation in Sanity (colors, type sizes, heading levels).
• Put stega strings in <head> or use them as hrefs/classes without stegaClean.
• Use array index as a list key — use _key.
• Add tailwind.config.js.
• Mix blocks/, layout/, and ui/.
• Init Lenis or run reveals when prefers-reduced-motion: reduce.
• Change the fluid root font-size snippet.
• Retune the design system anywhere except tokens.css.
• Fetch Sanity except through loadQuery.
• Add a sitemap that includes /styleguide.
• Commit .env or tokens.
• Skip typegen after schema/query changes.
• Use sanity schema extract / Studio APIs from memory — verify against installed package versions (@sanity/icons export style, TypeGen CLI, Tailwind v4 @theme).

Deployed draft preview

Production stays static, flag false. Hosted preview: SSR adapter, output: 'server', PUBLIC_SANITY_VISUAL_EDITING_ENABLED=true on preview only, CORS + SANITY_STUDIO_PREVIEW_ORIGIN for that origin.