SEMBLANCE STUDIOS — Build Specification

Technical reference for Claude Code · Updated: June 2026

---

TECH STACK

---

CMS DECISION (resolve before build)

The earlier spec assumed Sanity. Reconsider before committing, because it affects build complexity. The site is content-light and stable: six homepage sections, four to five project case studies on a repeating template, one Work section, an About page. None of it changes frequently.

Two options:

• Static (markdown/content files in Astro) — simpler, faster to build, no external service, same approach as the fine art site. Project case studies live as content files; adding a project means adding a file and pushing. Best fit for a side hustle with infrequent updates.
• Sanity — only worth it if projects will be added regularly by someone who shouldn't touch code, or content needs editing without a rebuild. More setup, more moving parts.

Recommendation: start static. Add Sanity later only if update frequency justifies it. The build spec below is written to work either way; the page structure and content are identical regardless of where the content is stored.

---

RESEND SETUP

1. Create free account at resend.com
2. Go to API Keys → Create API Key → name it "semblance-studios"
3. Give Claude Code the API key during the build
4. Tell Claude: "Set up Resend so all contact form submissions are sent to gavin@semblancestudios.com"
5. Test the contact form after deployment — confirm emails arrive before going live

---

VIEW TRANSITIONS (NON-NEGOTIABLE)

```astro import { ViewTransitions } from 'astro:transitions'; <ViewTransitions /> ```

---

SITE STRUCTURE (Locked — June 2026)

Navigation: HOME · PROJECTS · THE WORK · CREATIVE DIRECTOR · CONTACT

Homepage — SIX sections, scrollable, static (no carousel)

1. Hero — headline + supporting line over a locked architectural interior image
2. Positioning / Differentiator — three spaced sequential statements, generous white space, no image. The "studios work from a catalogue, Semblance works differently" copy.
3. Recent Projects — ONE featured project (not a grid), editorial image, single CTA to the Projects page
4. The Work — curated style references, one 16:9 composite per style direction (artwork detail + interior context in a unified frame), short mood-based descriptor per image
5. Creative Director — short teaser, CTA to the Creative Director page
6. Contact CTA — "Ready to discuss a project?" + CTA to Contact

Sub-pages

• Projects (/projects/) — grid of all executed commissions; each opens a full case study on the repeating template (intro copy → blocks of brief copy + in-situ image + artwork detail). Launch projects: BoTree, Meyer Werft, Singita, Rockefeller. Saatchi/ Florida added later, pending client approval.
• The Work (/the-work/) — the full style-direction gallery (same visual language as the homepage section, expanded). Style references, not a catalogue. No collection names, no numbered pieces.
• Creative Director (/creative-director/) — who leads the work and why to trust them; commercial credibility leads, fine art credentials support.
• Contact (/contact/) — enquiry form (Resend) routing to gavin@semblancestudios.com.

BUILD SEQUENCE (framework first, assets later)

Do not wait for the outstanding visuals before starting the build. The structure, page templates, navigation and full design system do not depend on final assets, and building them first is the correct order, not a workaround.

1. Scaffold against placeholders. Build the site structure, the repeating project template, navigation and all six homepage sections using placeholder images at the locked specs (16:9, 2560×1440, WebP, 20% safe zone). Grey blocks are fine.
2. Lock the design system first. Get the look consistent across three or four template types (homepage, a project case study, The Work, Creative Director) before any real content goes in. This is where the design holds or drifts.
3. Drop real assets in as they finish. Each completed asset replaces its placeholder in a slot that already exists. No structural work waits on it.
4. Copy follows the same pattern — Singita and Rockefeller slot into the built template once written.

design.md is the anchor for all of this. Extract it from the Aesthetic Direction section before the first session, attach it at the start of every Claude Code session, and reference it by name when building any new page or section ("use design.md for all visual decisions"). Build the framework against it before real content. Design drift — page one intentional, page four wandering — comes from not re-anchoring each session; design.md attached every time is the fix.

---

REMOVED / CUT (June 2026 decisions)

Note: The earlier project-instructions doc listed seven homepage sections and a Process page. This spec supersedes it — six sections, no Process page.

---

AESTHETIC DIRECTION

Register: Luxury without loudness. Authoritative without coldness. Creative without chaos.

Feeling on landing: Walking into a serious, considered studio — not a gallery, not a SaaS product, not a photographer's portfolio.

Colour:

• Warm cream: #F5F0E8
• Dark charcoal: #1C1C1A
• Terracotta accent: #C17A4A
• Warm neutrals as base. Bold colour as controlled accent. Not stark white, not cold grey.

Typography:

• Headings: LexendTera Regular
• Body: Playfair Display Regular
• Distinctive and elevated. Editorial character — not corporate, not generic. No Inter, no system fonts.

Layout: Generous negative space. Let the work breathe. Strong silhouettes. Asymmetry where purposeful. Alternating section backgrounds on scroll.

Motion: Subtle only. View Transitions for pages. Quiet entrance animations at most. Nothing that distracts from the work.

What it must NOT look like:

• Generic SaaS/startup (purple gradients, Inter font, feature grids)
• Cold white-box gallery aesthetic
• Busy photography portfolio with thumbnail grids everywhere
• Over-produced with excessive animations

---

DESIGN.MD (create before first build session)

After this spec is final, extract all aesthetic decisions above into a standalone design.md in the project root. This prevents design drift — where the first page looks intentional and every subsequent page diverges from it.

design.md must include:

• Colour palette: exact hex values for all colours and the role of each
• Typography: font names, weights, hierarchy rules (H1, H2, H3, body, captions)
• Spacing system: base unit, margin and padding conventions
• Component rules: button styles, card behaviour, link treatment
• Layout principles: negative space, asymmetry rules, section background alternation
• Motion rules: what is and isn't permitted
• The exclusion list — what the site must NOT look like

How to use it: save as design.md in the project root, attach at the start of every Claude Code build session, and reference it explicitly when adding any new page or section ("Use design.md for all visual decisions"). The raw material already exists in the Aesthetic Direction section above — format it into the standalone file before the first build session.

---

SKILLS STACK

---

PRE-BUILD SETUP

CLAUDE.md

Create before writing code, via interview-style process: "I want to build a CLAUDE.md file for a website build project. Ask me interview-style questions to extract all the context — the business, the client, the aesthetic direction, the technical requirements, and how I like to work. Then compile into a well-structured CLAUDE.md file."

Must cover: what Semblance is and is not; who the clients are; the site's single goal (get procurement firms to make contact); the six-section homepage and confirmed copy; tone and aesthetic; technical requirements (Astro, View Transitions, Cloudflare, Resend, and the CMS decision); what the site must NOT look like; the Work-section mobile treatment; image specs (16:9, 2560×1440, WebP, 20% safe zone); SEO baked in from day one.

memory.md

Manual file in project root. At the start of each session: "Read memory.md before starting. When I correct you or you learn a preference, update memory.md immediately."

End-of-Session Blocker Review

At session end: "Review what we worked on. Identify one place where you had to stop and wait for me, or were uncertain. What could I document or add to CLAUDE.md or memory.md to prevent that blocker next session?"

Permission Mode Sequence

1. First session: Ask Permissions
2. Once comfortable: Auto Accept Edits
3. Experienced sessions: Bypass Permissions

MODEL NOTE (which Claude to build with)

Model choice is a minor lever for this build, and reaching for Fable specifically is not the advantage it looks like.

• Workhorse: Opus 4.8 or Sonnet 5. Sonnet 5 (released end of June 2026) is the cheap, highly agentic option and is well-suited to a static marketing-site build; Opus 4.8 is the reliable default. Use these for the bulk of the work.
• Fable is escalation-only. It returned on 1 July, is included up to ~50% of weekly usage through 7 July, then moves to metered credits at roughly double Opus 4.8's rate. Reach for it on a genuinely hard stretch, not as the daily driver.
• A clean "all-Fable" build isn't possible anyway. The safeguards classifier shipped with Fable's return over-flags benign coding and debugging and reroutes those requests to Opus 4.8, with different style and cost. Selecting Fable does not mean Fable does the work.
• The real gate is upstream — outstanding assets and pre-build setup, not the model. Don't spend effort optimising model choice.

(Availability and pricing as of early July 2026 — verify current terms if it affects spend.)

---

IMAGE SPECIFICATIONS (Locked)

• Aspect ratio: 16:9
• Resolution: 2560 × 1440px
• Format: WebP
• Safe zone: all critical content within centre 70% of frame — 20% buffer minimum on all edges
• Applies to: every full-width image across the entire site
• Exception: artwork detail images retain their native aspect ratio
• Astro handles optimisation natively (format conversion, resizing, lazy-loading) — confirm it's set up during build given the image-heavy nature of the site

---

SEO NON-NEGOTIABLES

• Schema markup: LocalBusiness + CreativeWork types
• Proper heading hierarchy (H1, H2, H3)
• Semantic HTML throughout
• Core Web Vitals optimised (Astro handles most of this)
• XML sitemap
• Clean URL structure
• Open Graph tags for social sharing
• Descriptive, keyword-relevant image alt text on all portfolio images
• Mobile-first responsive design

Core keywords: custom artwork for hotels · bespoke art for hospitality · art for hotel interiors · custom art for luxury developments · hospitality artwork studio · art procurement Cape Town · bespoke art cruise ships

---

CONTENT STATUS

*Reflects the real state as of the latest review. The framework can be built against placeholders while the outstanding assets are finished — see "Build sequence" below. The earlier "visuals essentially complete" status was optimistic; the accurate picture is below.*

Foundations — done:

• Copy direction, messaging and site flow locked
• Stack decided (Astro / static content / Cloudflare / Resend)
• Domain, Cloudflare, Google Workspace and DKIM set up
• The site build itself has not started

Copy — locked:

• Hero, positioning / differentiator, homepage section descriptors
• Meyer Werft (all four spaces), BoTree intro
• Creative Director page, contact form

Copy — still to write:

• Singita page
• Rockefeller page
• (Both follow the repeating project template, so they're fast once the baseline pages exist)

Visuals — outstanding (this is the real gate on a finished, launchable site):

• The Work — anthurium still life in development; Afrika figure needs its final hat generation; abstract works 02–05 unresolved; in-situ composites still to produce
• Meyer Werft — boat headpiece portraits still to create at 3:4
• Singita — bedroom composite needs the white-mat fix
• Artlink / Maaian — figurative and botanical directions for the client presentation (its own thread, separate from the site build)

Visuals — done:

• Hero / landing image. Treat everything else as outstanding until confirmed against the actual asset files.

---

TESTIMONIALS

Three confirmed sources, outreach drafted (send before build):

• Senior curator, Saatchi Art (New York) — homepage, after The Work. Frame around working relationship, not the Florida project specifically.
• Lead curator, Artlink — BoTree project page
• Lead curator, Artlink — Meyer Werft project page

Format: pull quote, large restrained type, name/title/company below. No star ratings, no carousel. Do not build placeholder testimonial blocks — quotes confirmed and approved before build, or the section doesn't exist at launch.

---

BUILD PREPARATION CHECKLIST

Setup:

• [ ] Download Claude Code Desktop app
• [ ] Resolve CMS decision (static vs Sanity)
• [ ] Enable permission mode per sequence above

Skills:

• [ ] Verify obra/superpowers working
• [ ] Run uipro init --ai claude inside project folder before building

Content preparation:

• [ ] Write Singita page copy
• [ ] Write Rockefeller page copy
• [ ] Send testimonial outreach
• [ ] Create design.md from Aesthetic Direction section
• [ ] Confirm final count of The Work style-direction composites
• [ ] Chase Saatchi/Florida client approval (for later addition)

---

IMPLEMENTATION TIMELINE

---

PARKED / LATER (NOT FOR LAUNCH)

---

POST-LAUNCH — PHASE 2 (light marketing plan)

Keep Phase 2 proportional — Semblance is the side hustle. Finish the website and a light marketing plan; resist scope creep beyond that.

---

QA PROTOCOL (BEFORE LAUNCH)

Click through the entire site like a real user — contact form submission, mobile rendering at different sizes, all navigation links, project pages loading, The Work responsive behaviour. Sign off as live only once complete and all issues resolved.