Design

Narrative

The data/ and data-metric/ families grew independently. data/ components are standalone display widgets built for various needs. data-metric/ components are composable building blocks for single-value display with optional decorations (sparkline, trend, percent bar). Without a clear map, contributors couldn't tell which family to reach for.

Rename scope was larger than expected — layer source, design demos, design registry, app production pages, app lib docs, app dev pages, app registry, app skills, and app agents all needed updating. Separating the audit/classify/rename phase from actual migration of deprecated components kept the cycle manageable. The deprecated data/ components still work; migration happens incrementally.

Narrative

Dev components are the foundation for every other component demo. DevCanvas, DevFrame, DevComment, DevControls — these are what contributors use to build and test new demos. Documenting them makes the demo-building workflow discoverable.

Hiding dev and dev-controls from the public components index keeps the consumer-facing view clean while making the tooling fully browsable for contributors who navigate directly.

Narrative

The audit revealed systematic gaps, not one-offs. healthMode was never exposed across 8 data-metric demos. v-model components didn't expose modelValue. 76 of 87 demos only exercised the default state with a single data scenario. Making this visible was enough to motivate filling it — no gates or thresholds needed.

The adminProps kind: system (range, options) scaled well. Adding healthMode as a dropdown across all data-metric demos required no custom UI per demo. The structured prop types that c17 introduced paid off immediately.

Narrative

The instinct to keep the layer "pure" — only generic primitives, no domain components — doesn't survive scrutiny. Nuxt tree-shakes aggressively, so unused components cost nothing at runtime. A single pantry is strictly better than splitting across repos.

Deleting app's local DevCanvas forks was the proof point. Same props, same v-model pattern — the only difference was visual styling. Layer versions have dark theme and polished CSS. Local overrides remain the escape hatch: Nuxt prioritizes local components, so any consumer can override by placing a local copy.

Narrative

The default slot from c19 was only ever used for a violations table — it wasn't a generic composition point. Promoting the table to a standalone component and switching to a prop keeps the layout logic contained.

ViolationsTable serves dual purpose: PolicyCard uses it internally for the summary view, and the security policy detail page can use it directly for the full dataset. Prop over slot when the content type is always the same.

Narrative

The security policy page needed cards for whitelisted apps, datastores, and vendors that share PolicyCard's visual treatment but with completely different content. The visual wrapper was baked into PolicyCard alongside domain-specific stats.

Extracting PolicySkin follows the same pattern as the sentence builder extraction: recognize when a component contains a reusable primitive, pull it out, compose back together. PolicyCard is now PolicySkin + domain content, not a monolith.

Narrative

The alert config started as a local pattern prototype with inline render-function sub-components. Extraction to the layer revealed the pill inputs and sentence rows weren't alert-specific — they're a generic "sentence builder" pattern reusable in filters, rules, and config UIs.

Key discovery: UxToggle is already a <label> element. Wrapping it in another <label> creates invalid HTML. The #label slot is the correct API for dynamic label content.

Narrative

The security dashboard vision from c11 showed policies with adjacent violations tables. The PolicyCard was props-only — no way to compose detail content alongside it. Adding a default slot follows the layer's composition-over-configuration principle: the card handles its own rendering, the consumer decides what goes next to it.

SecurityDataFlow captures a core Qpoint concept — the visual pattern of data flowing from source through typed tags to destination. Having it as a shared component means every security-related view can render data flows consistently.

Narrative

After 16 cycles of building the design system, the design site itself was still utilitarian. This cycle started applying the brand's own visual identity — Swiss-modern aesthetic, deliberate typographic hierarchy, generous whitespace — to the tool that documents it.

The three-state view mode (Full/Work/Focus) reflects how the site is actually used: sometimes you need the docs, sometimes you just need the canvas. Persistent preferences via usePreference mean the site remembers how you work.

Narrative

The Sortable Data Table was deferred from c6 because the sort metric API felt too app-specific. The breakthrough was showing both levels: a flat composition (simple) and a full production decomposition (complex, drawn from traffic/connections). The pattern is accessible at both levels.

Sticky header was the original motivation for UxTableList. The scroll event callbacks depend on #page-scroll-window — sticky positioning works in any scroll container, but the event chain requires the matching element ID. This kind of implicit contract is exactly what compositional guides exist to surface.

Narrative

The Figma MCP output is useful but noisy — data-node-id attributes, expiring image URLs, inline style overrides all need cleanup. But layout structure, size variants, and color values transfer cleanly. The pipeline is repeatable.

The /layer page closes the communication gap. Engineers and collaborators can now see what the layer provides, how it works, and why it's built this way — without reading CLAUDE.md files or source code.

Narrative

The Qpoint ecosystem has 8+ projects, each with deep domain specialization. Cross-project collaboration required manually knowing which project had what data. Now each project's CLAUDE.md declares its neighbors — when to use them, key data paths, and available agents or skills.

Documentation as API, not MCP. For internal AI agent work, file reads via additionalDirectories are simpler and sufficient. Peer-to-peer, not hub-and-spoke — every project declares its own capabilities.

Narrative

@nuxt/content strips the content/ directory prefix from component auto-imports. Renaming to prose/ eliminated the collision cleanly — no filename workarounds needed. The directory-based prefix now works as Nuxt intends.

www.qpoint.io ended with zero local copies of any of the 12 prose components. One duplicate was found during extraction — point/Big.vue was an exact copy of the already-extracted ContentBigPoint. This kind of invisible duplication silently accumulates. Extraction surfaces it.

Narrative

Composition over configuration, cycle-based development, pattern discovery, replicate-first — these principles were already operational before the thesis connection was made explicit. The methodology was already embedded in the practice. It needed language.

The key insight: writing "in the voice of" rather than "about" the thesis produced artifacts that read as natural extensions of the brand. Academic citations would have created distance. The ideas are absorbed, not referenced.

The agent-era connection emerged as the strongest untapped angle. "Collective sketching" and "shared consciousness" describe exactly what MCP servers and CLAUDE.md files do for AI agents. Kept internal for now.

Narrative

Individual component demos show what each piece does. Patterns show how they compose together — that's where the real value lives. Feature Grid is SectionHeadline + LayoutGrid + BigPoint. Process Steps is StepWrapper + Step. The combinations recur 20+ times across www pages.

The /scan-patterns skill formalized what had been a manual process: read pages from a sister project, identify layer component compositions, group by similarity, report frequency. It found 5 app patterns in app.qpoint.io — 4 clean enough to document immediately, 1 (Sortable Data Table) too coupled to its app context.

Narrative

Connecting app.qpoint.io to the layer was the real test. The styleguide and www were already consuming it, but the product app had the most components and the most edge cases.

Every integration pain revealed a layer bug — relative imports that broke in consumers, Tailwind tokens defined only in the app's config. The consumer setup pattern crystallized: tarball dependency, extends config, cssPath false, remove local @tailwind directives. All three consumers now follow the same recipe.

Narrative

The design site was serving three roles simultaneously: distributable design system, brand knowledge base, and showcase website. An isSite flag in the config — conditional logic detecting whether the project was running as a site or being consumed as a layer — signaled these roles wanted to be separate.

The split created two projects with clear identities. The layer is unconditional (~25 lines of config). The design site is a standard Nuxt app that extends it. When the design site feels integration pain, other consumers will too.

Component philosophy was codified: composition over configuration, Tailwind-native, slots over deep prop trees. These principles would guide every extraction that followed.

Narrative

A working MCP server that makes Qpoint's brand identity programmatically available to Claude Code and any MCP-compatible AI client. Standalone Node.js process using stdio transport, separate from the Nuxt app. Imports brand data directly from server/data/brand.ts — zero duplication, single source of truth preserved.

The check-brand-voice tool is the first concrete example of brand enforcement rather than brand documentation. In its first test, it correctly caught three violations in a single sentence — an exclamation point, a superlative, and "We" as a marketing headline subject — and suggested compliant rewrites.

The style guide website remains the human-readable reference. The MCP server is the machine-readable one. Same source data, two interfaces.

Narrative

A new working document exploring the concept of a brand-aware MCP server — a service that would make Qpoint's brand knowledge programmatically available to any AI assistant used by the team.

Three capability layers: resources (brand content on demand), tools (brand-specific AI actions), prompts (pre-built templates). Four concrete use cases demonstrate range — from voice review to asset delivery to audience-specific messaging coaching.

This document marks a meaningful inflection point in how Qpoint thinks about its brand system. The style guide has always been a document — something people read (or don't). The MCP server concept reframes the brand as a service — something AI tools consume automatically.

This connects directly to the v1.5 elevation of the MCP server as a first-class product capability. The brand is now thinking about MCP not just as a product feature for customers, but as internal infrastructure for how the team itself operates.

Narrative

Two major things happen in v1.5. First, the AI governance pivot: "vibe-coded apps" enters the language as a specific threat vector. The MCP server is elevated to a first-class capability. The vision shifts from empowerment to automation — suggesting Qpoint acts on your behalf, not just informs you.

Second, Section 2 begins. The brand's tangible identity starts taking shape. Grape as primary color is deliberately non-blue, aligning with competitive differentiation. Color is framed as functional, not decorative. Semantic colors are marked as placeholders — honest about what's decided and what isn't.

Narrative

The most meaningful structural shift in v1.4 is the move from product-first to problem-first framing. Instead of opening with what Qpoint does, it leads with the question that security and platform teams can't answer.

Technical specificity increases: "deep, kernel-level" enters the language. The stable core — values, persona, voice, writing principles — remains untouched.

Narrative

The foundation is clean and finished. Dual emphasis on visibility and control is established as a first principle. Three-dimensional coverage (egress, internal, endpoints) is introduced inline in the opening paragraph.

The voice is confident and peer-level. The persona — the senior engineer who's already solved the problem — is set. Values, writing principles, and the decision framework are locked in and will remain unchanged through subsequent versions.