WebCraft

The challenge

Projects, components, development guides, and focused tools are often scattered across separate places. A conventional portfolio can show an outcome without explaining the constraints, design judgment, or engineering decisions behind it. WebCraft needed to make those decisions legible while protecting private implementation records and leaving room for long-term growth.

Constraints

• Use free or low-cost technology choices first.
• Keep Server Components primary and Client Islands focused.
• Avoid a database or CMS during the early content stage.
• Keep private implementation records and repository details out of public releases.
• Require lint, typecheck, tests, build, and production acceptance for formal releases.
• Support keyboard access, mobile layouts, and reduced-motion preferences.
• Maintain independent histories for implementation and public repositories.

Key decisions

1. Static-first architecture

   Why

   The first release has a focused content scope, and static data is easier to audit, test, and publish than an early database or CMS.

   Result

   Formal routes generate at build time, the content model can grow later, and no runtime data service is required today.

2. Server Components with focused Client Islands

   Why

   Most page content is for reading, while copying code and component previews are the only areas that need local browser state.

   Result

   Page structure stays server-rendered, client boundaries remain auditable, and full-page hydration is avoided.

3. Typed content contracts

   Why

   Projects, guides, and components need stable data boundaries, and pages should not depend on a specific content source.

   Result

   Manifests, adapters, and normalized models remain separate, completeness can be tested, and future sources can be added without rebuilding pages.

4. Shared Fluid Material system

   Why

   Projects, Components, Guides, Playground, and Design System need consistent hierarchy, spacing, material, and interaction feedback.

   Result

   The product surfaces share a coherent visual language, with responsive and focus behavior that can be verified consistently.

5. Quality-gated releases

   Why

   Automatic deployment does not replace quality judgment, so each formal release needs repeatable static checks and production verification.

   Result

   GitHub Actions validates public commits, Vercel deploys from public main, and each production release has a traceable commit SHA.

6. Separate implementation and public repositories

   Why

   Private engineering records must remain protected while public code needs to stay clear, reproducible, and trustworthy.

   Result

   The implementation repository remains the source of work, the public repository is a reviewed release mirror, and production routes exclude private paths and content.

Architecture

1. Typed content

   Verified manifests and shared TypeScript contracts define the content boundary.

2. Feature modules

   Projects, components, guides, and tools keep their domain logic close to their routes.

3. Server-rendered routes

   Static reading surfaces render on the server and remain directly indexable.

4. Focused client interactions

   Only local controls such as code copying and live component previews need browser state.

5. Automated quality checks

   Linting, type checks, tests, and builds create a repeatable release gate.

6. Vercel production

   Reviewed public main commits become traceable production deployments on the formal domain.

What shipped

• Multiple static product routes with page metadata.
• A Project Manifest, Adapter, and normalized query model.
• Guides directory navigation, section anchors, and code-copy feedback.
• Interactive Button, Form Field, Switch, and Accordion previews.
• A public Design System reference for semantic tokens, Fluid Material levels, motion, and accessibility foundations.
• A responsive Playground with tabbed source editing and isolated layout diagnostics.
• GitHub Actions quality checks.
• Vercel Git-driven production deployment.
• A custom domain with HTTPS, canonical URLs, sitemap, and robots.
• Keyboard, mobile, reduced-motion, and private-path protection acceptance checks.

Outcomes

• The formal site is publicly available through its custom domain.
• A Git push can trigger a quality-checked production deployment.
• Formal routes generate at build time and have been checked in production.
• Canonical URLs, sitemap, and robots use one formal domain.
• Components and Guides include real interaction instead of static-only display.
• The page shell has no horizontal overflow at a 390px viewport.
• Keyboard interaction and native semantics have been checked in a real browser.
• Private rules and engineering paths remain unavailable in production.

Lessons learned

• Set repository and module boundaries before adding capability.
• A small number of complete interactions is more valuable than many static examples.
• Native HTML semantics are safer than custom keyboard simulation.
• A successful automatic deployment is not the same as completed release acceptance.
• Static architecture is sufficient for an early product stage.
• Data models should serve verified content, not abstraction for its own sake.

Next iteration

• Add more verified real project case studies.
• Expand the catalog with mature component categories.
• Add more bounded, practical local examples where they can be verified.
• Add clearer project evidence and visual material where it can be verified.
• Reassess a CMS or external data source only when content scale requires it.