# Design Language for sbom.wiki ## Aesthetics and Tone sbom.wiki is an educational wiki about Software Bill of Materials -- a concept rooted in supply chain transparency and software component traceability. The visual direction channels the spirit of **Muji's design philosophy**: stripped of decoration, honest about its materials, quietly confident in its structure. Imagine a well-organized Japanese stationery shop where every item has been considered, every shelf label hand-lettered with care, and the shelving itself is as beautiful as the goods it holds. The tone is **approachable-casual** -- like a knowledgeable colleague sketching out a concept on a whiteboard with a felt-tip marker. Nothing about the experience feels corporate or sterile. Instead, it feels like opening a beautifully curated notebook where someone has hand-drawn diagrams of how software components fit together, annotated with casual handwriting in the margins. The SBOM concept (tracking software ingredients like a food label tracks ingredients) is inherently about making hidden complexity visible -- and the design should mirror that ethos: transparent, honest, slightly informal, deeply organized. The aesthetic avoids the glossy tech-startup look entirely. No gradients pretending to be futuristic. No dark-mode neon dashboards. Instead: warm unbleached paper textures, pencil-sketch component diagrams, subtle kraft-paper card edges, and the satisfying visual rhythm of a well-maintained inventory ledger. Think of it as the intersection between a Japanese packaging design manual and a hand-illustrated field guide to software ecosystems. ## Layout Motifs and Structure The layout follows a **Z-pattern** reading flow, guiding the eye from top-left branding to top-right navigation, diagonally across a central illustrative content zone, then from bottom-left supporting material to bottom-right action/exploration areas. This Z-pattern is not imposed rigidly but expressed through intentional visual weight distribution and directional cues -- hand-drawn arrows, subtle dotted connector lines, and offset content blocks that pull the eye along the Z diagonal. **Structural Framework:** - **Header Band (8vh):** A narrow, warm-toned (#f5f0e8) band containing the site wordmark (left, hand-drawn logotype) and sparse navigation links (right, underlined on hover with a slow hand-drawn underline animation). The band has a faint bottom border rendered as a slightly irregular pencil line using an inline SVG path with subtle wobble. - **Z-Diagonal Content Zone (full viewport):** The primary content area is organized around the Z-pattern. The top-left quadrant holds the primary concept introduction (a large slab-serif heading with a hand-drawn bracket motif). The top-right quadrant holds a small interactive component-tree diagram. The center diagonal is a prominent hand-drawn illustration of an SBOM dependency graph -- sketchy nodes connected by pencil-stroke edges. The bottom-left holds explanatory paragraphs. The bottom-right holds navigation tiles to deeper wiki sections, styled as kraft-paper index cards. - **Progressive Disclosure Sections:** Below the Z-pattern hero, content is organized into collapsible sections that expand with a gentle elastic easing. Each section header is styled as a hand-lettered label on a tab, evoking the tabs of a physical filing system. Sections expand to reveal detailed wiki content, diagrams, and annotated code examples. Only the first section is open by default -- the rest invite exploration through subtle visual hints (a faint pencil arrow, a "peek" of content visible as a 2-line preview). - **Grid-Line Substrate:** The entire page background features a barely-visible grid-line pattern (#e8e3da at 8% opacity on #f5f0e8 background) -- like graph paper or an engineering notebook. This grid is not decorative noise; it is the structural skeleton. Content blocks align to this grid, and hand-drawn diagram elements use the grid lines as their coordinate system, creating a sense that the entire page is a working document. - **Margin Notes:** Occasional annotations appear in a right-margin column (visible on viewports > 1200px, collapsed into expandable tooltips on smaller screens). These margin notes are styled in a smaller, slightly rotated handwritten font, as if someone has annotated the page with additional context. ## Typography and Palette **Typography:** - **Headlines / Section Titles:** "Roboto Slab" (Google Fonts) -- a geometric slab-serif with sturdy, machine-cut bracketed serifs that evoke technical documentation and inventory labels. Used at 2.8rem-4.2rem for primary headings, 1.8rem-2.2rem for section titles. Weight: 400 (Regular) for approachable warmth, 700 (Bold) for key definitions. Letter-spacing: +0.01em. Line-height: 1.2. The slab-serif character reinforces the "catalog" and "registry" metaphor -- SBOMs are registries, and the typography should feel like a well-typeset registry page. - **Body Text:** "Source Sans 3" (Google Fonts) -- a clean humanist sans-serif designed for readability at small sizes, with open apertures and a warm personality that avoids sterility. Used at 1rem-1.125rem for body paragraphs, 0.875rem for captions and margin notes. Weight: 400 (Regular) for body, 600 (SemiBold) for inline emphasis. Line-height: 1.65. Max line width: 68ch. - **Annotations / Handwritten Elements:** "Caveat" (Google Fonts) -- a semi-cursive handwriting font with natural stroke variation that reads as genuine handwriting rather than a font. Used at 0.875rem-1.125rem for margin notes, diagram labels, and casual annotations. Weight: 400. Slightly rotated (-1deg to +2deg) per element to create organic variation. - **Code / Technical Specimens:** "IBM Plex Mono" (Google Fonts) -- a monospaced font with humanist proportions, used for SBOM format examples (SPDX, CycloneDX), dependency lists, and inline code. Used at 0.85rem. Weight: 400. Background: #f0ebe2 with a 1px solid #d9d0c0 border, 4px border-radius. **Palette (Triadic Foundation):** The triadic palette is built from three hues equidistant on the color wheel, desaturated and warmed to fit the Muji aesthetic: - **Primary: Warm Ochre** `#c4956a` -- The anchor tone. Used for headings, active states, interactive elements, and the hand-drawn diagram node fills. Evokes kraft paper, wooden shelving, and warm stationery. - **Secondary: Sage Teal** `#6a9e8f` -- The complement. Used for links, secondary buttons, diagram edge strokes, and the grid-line accent color. Evokes the green ink of a ledger book. - **Tertiary: Dusty Plum** `#8f6a7e` -- The accent. Used sparingly for highlights, notification badges, and margin-note emphasis. Evokes a soft wax seal or bookbinder's cloth. - **Background: Unbleached Linen** `#f5f0e8` -- The paper. The base surface for all content. Not pure white -- it has the warmth of unbleached cotton paper. - **Surface: Kraft** `#ede5d8` -- Card backgrounds, collapsible section surfaces, and code block fills. Slightly darker than the background, creating gentle elevation without shadows. - **Text: Charcoal Ink** `#2d2a26` -- Primary text color. Not pure black -- it is a warm, dark brown that reads as ink on paper. - **Muted: Pencil Gray** `#8a8279` -- Secondary text, placeholder text, and disabled states. The color of a soft pencil mark. - **Grid Lines:** `#d9d0c0` -- The engineering-notebook grid. Visible but never dominant. ## Imagery and Motifs **Hand-Drawn Diagram System:** The defining visual element of sbom.wiki is a comprehensive hand-drawn illustration system for depicting software component relationships. Every diagram on the site -- dependency trees, vulnerability chains, license inheritance graphs -- is rendered in a sketchy, hand-drawn style using SVG paths with slight wobble applied via a custom stroke-dasharray and subtle `feTurbulence` SVG filter (baseFrequency: "0.04", numOctaves: 2, scale: 2). Nodes in the diagrams are rounded rectangles with slightly uneven corners (each corner radius varies by 1-3px). Edges are drawn as slightly curved paths with arrowheads that look hand-sketched. The overall effect is a whiteboard diagram drawn by an expert -- precise in its content but organic in its rendering. **Grid-Line Background Pattern:** The page background carries a persistent grid-line pattern: thin horizontal and vertical lines at 24px intervals, rendered in `#d9d0c0` at 40% opacity. This creates the engineering-notebook substrate that all content sits upon. At the intersection of every 4th gridline (96px intervals), a slightly thicker dot appears, creating a subtle dot-grid overlay that helps the eye gauge distances. The grid is implemented as a CSS `repeating-linear-gradient` layered with a `radial-gradient` for the intersection dots. **Kraft-Paper Index Cards:** Navigation elements and content summaries are presented as kraft-paper index cards -- rectangular blocks with a `#ede5d8` background, a faint `#d9d0c0` top-border (like the ruled line at the top of an index card), and a subtle `box-shadow: 2px 2px 0px #d9d0c0` to create a stacked-paper effect. On hover, cards shift `transform: translate(-1px, -1px)` with the shadow growing to `3px 3px 0px #d9d0c0`, as if the card is being lifted slightly from the stack. **Pencil-Stroke Decorative Elements:** Section dividers are not clean horizontal rules but hand-drawn pencil lines -- SVG paths with 5-7 subtle control points creating a gently undulating line. Each divider is slightly different (3-4 pre-drawn variations randomly selected). Similarly, bracket motifs (drawn as slightly imperfect curly braces) frame key definitions and highlighted quotes. **Component-Tree Motif:** A recurring visual motif is the component tree -- a branching structure that appears as a subtle watermark behind section headers (at 5% opacity) and as interactive, fully-rendered diagrams within content sections. The tree branches at 60-degree angles, with each leaf node rendered as a small rounded rectangle containing a truncated package name in IBM Plex Mono at 10px. **Tab Filing System:** Section headers for the progressive-disclosure sections are styled as physical filing tabs -- small trapezoidal shapes protruding from the top-left of each collapsed section, containing the section title in Caveat at 0.9rem. The active/expanded tab has a warm ochre (#c4956a) fill; inactive tabs are #ede5d8 with a #d9d0c0 border. Tabs are implemented as CSS clip-path trapezoids. ## Prompts for Implementation **Full-Screen Narrative Experience:** The site opens as a blank sheet of graph paper. On initial load, the viewport shows only the grid-line background (#f5f0e8 with #d9d0c0 grid) -- an empty notebook page. After a 0.5-second pause, a pencil-drawing animation begins: the site wordmark "sbom.wiki" is drawn stroke-by-stroke in the center of the viewport using SVG path animation (`stroke-dashoffset` transitioning from full-length to 0 over 1.8 seconds with an ease-in-out timing function). The wordmark is rendered in Roboto Slab outlines, but drawn as if by hand -- each letter's path has slight wobble. As the wordmark completes, the central hand-drawn SBOM diagram begins to sketch itself in: nodes appear one-by-one (opacity 0 to 1 with a slight scale from 0.9 to 1.0, staggered by 120ms), then edges draw themselves between nodes using the same stroke-dashoffset technique (200ms per edge, staggered). The entire diagram assembly takes approximately 3 seconds and creates the sense of watching someone sketch out a concept in real-time. **Progressive Disclosure Navigation:** Below the hero diagram, wiki sections are presented as a stack of collapsed filing-tab sections. Each section reveals only its tab label and a 2-line preview (the first sentence of content, shown in #8a8279 at 0.875rem). Clicking a tab triggers a smooth expansion animation: the section height interpolates from its collapsed preview height to its full content height over 400ms with a cubic-bezier(0.34, 1.56, 0.64, 1) easing (slight elastic overshoot). Simultaneously, the tab fill transitions from #ede5d8 to #c4956a over 250ms, and the preview text transitions to full-opacity #2d2a26 body text. Only one section is open at a time (accordion behavior). When a new section opens, the previously open section collapses with a matching 400ms animation. The viewport scrolls smoothly to position the newly opened section's tab at 10vh from the top of the viewport. **Z-Pattern Directional Cues:** Hand-drawn arrows (SVG paths with wobble filter) subtly guide the eye along the Z-pattern. A small pencil-sketch arrow in the top-right area of the hero points diagonally down-left toward the central diagram. Another arrow near the bottom-left of the diagram points right toward the wiki section navigation. These arrows are rendered at 25% opacity and use a slow breathing animation (opacity oscillating between 0.2 and 0.35 over 3 seconds) to draw attention without demanding it. **Storytelling Approach:** The site should tell the story of "what is inside your software?" as a journey of progressive discovery. The narrative moves from the simple (a single software package) to the complex (a full dependency tree with transitive dependencies, vulnerability annotations, and license inheritance). Each progressive-disclosure section peels back another layer -- mirroring the SBOM concept itself: transparency achieved through systematic disclosure. **Animation Guidelines:** - All animations use CSS transitions or CSS @keyframes -- no JavaScript animation libraries - Easing: cubic-bezier(0.34, 1.56, 0.64, 1) for elastic reveals; ease-in-out for drawing animations - Duration: 300-500ms for UI transitions, 1-3 seconds for narrative drawing animations - Stagger delays: 80-150ms between sequenced elements - SVG path drawing: `stroke-dasharray` set to path length, `stroke-dashoffset` animated from full to 0 - Progressive disclosure: CSS `max-height` transition from a small value to a large value (not auto, which doesn't animate), with `overflow: hidden` **Avoid:** - CTA-heavy layouts, pricing blocks, stat-grids - Dark mode / neon color schemes - Corporate SaaS landing page patterns - Heavy parallax scrolling (the grid-line background should remain fixed, but content should not parallax against each other) - Stock photography of any kind - Glossy or high-contrast UI elements ## Uniqueness Notes **Differentiators from other designs:** 1. **Engineering-Notebook Grid Substrate:** While grid-lines as a motif appears in only 6% of existing designs, this design makes the grid the foundational visual element -- not a decorative overlay but the structural coordinate system that all content and diagrams are built upon. The graph-paper background is the design's "material truth," directly connecting to the SBOM concept of structural transparency. 2. **Hand-Drawn SVG Diagram System with Wobble Filter:** Rather than using static illustrations or photography (photography: 72%, minimal: 95%), every diagram is rendered as an interactive, animated SVG with a custom `feTurbulence` wobble filter that creates genuine hand-drawn aesthetics at the rendering level. The diagrams are not pre-drawn images -- they are dynamic SVG structures that draw themselves on scroll entry, creating a "watching someone think on paper" experience unique in the portfolio. 3. **Physical Filing-Tab Progressive Disclosure:** The accordion navigation system uses CSS clip-path trapezoids styled as physical filing tabs from a paper filing cabinet -- a metaphor that directly maps to the SBOM concept of organized component cataloging. This is not a generic accordion; it is a filing system rendered in code, complete with kraft-paper textures and hand-lettered tab labels in Caveat handwriting font. 4. **Triadic Palette at Muji Saturation:** The triadic color scheme (ochre/sage/plum) is desaturated to match the Muji aesthetic of quiet, natural materials. This is rare in the portfolio -- triadic palettes appear at only 2%, and the combination of triadic color theory with Muji-level restraint creates a palette that is simultaneously structured (color theory) and humble (material honesty). 5. **Z-Pattern with Hand-Drawn Directional Cues:** The Z-pattern layout (4% frequency) is reinforced not by sharp geometric arrows or bold visual blocks but by subtle, breathing, pencil-sketch arrows at 25% opacity -- a combination of structured layout theory and organic, hand-drawn execution that no other design in the portfolio achieves. **Seed/Style:** aesthetic: muji, layout: z-pattern, typography: slab-serif, palette: triadic, patterns: progressive-disclosure, imagery: hand-drawn, motifs: grid-lines, tone: approachable-casual **Avoided overused patterns:** playful aesthetic (95%), centered layout (99%), mono typography (99%), warm palette (100%), scroll-triggered patterns (96%), friendly tone (98%), vintage motifs (88%), minimal imagery (95%), photography imagery (72%), parallax patterns (74%), gradient palette (88%)