# Design Language for miris.works

## Aesthetics and Tone

miris.works channels the disciplined beauty of a Japanese computational atelier -- imagine a software documentation site reimagined through the lens of Naoto Fukasawa's product philosophy and Kenya Hara's white-space mastery, but rendered in deep jewel tones instead of the expected neutral palette. The aesthetic is **japanese-minimal** in structure but **jewel-rich** in surface: a deliberate collision between the restraint of *ma* (negative space as active compositional element) and the saturated intensity of sapphire, amethyst, and emerald drawn from Edo-period *kumihimo* braiding palettes.

The mood is that of a master craftsperson's workbench at twilight -- orderly, intentional, every tool in its precise location, but bathed in the deep colored light filtering through stained glass. There is no clutter, no ornamentation for its own sake. Every element earns its place through function. But the materials themselves are precious: jewel-toned backgrounds instead of white, gold-accented type instead of black, and isometric technical diagrams that feel like they were drawn on indigo washi paper with a gold-nibbed pen.

The tone is **tech-tutorial**: authoritative but patient, explaining with clarity and precision. Not friendly-casual, not corporate-stiff. The voice of someone who has mastered their craft and shares knowledge with the quiet confidence of someone who does not need to perform enthusiasm. Like reading documentation written by a Kyoto ceramicist who also happens to be a systems architect.

## Layout Motifs and Structure

The layout follows a **hero-dominant** composition with **layered-depth** spatial relationships. The page opens with a commanding full-viewport hero that establishes the jewel-toned atmosphere and the isometric visual language before transitioning into structured content sections that maintain generous negative space in the *ma* tradition.

**Structural Principles:**

- **The Tokonoma Hero:** The initial viewport functions as a *tokonoma* -- the Japanese alcove designed to display a single, carefully chosen object. Here, the hero presents one isometric illustration and a single line of display typography against a deep sapphire field. Nothing else. No navigation bar cluttering the top. No secondary text competing for attention. The navigation appears only after the first scroll interaction, sliding in from the left edge as a narrow vertical strip with icon-only links (text labels appear on hover via tilt-3d rotation).

- **Tatami Grid System:** Below the hero, content is organized on a proportional grid inspired by tatami mat arrangements. The base unit is a 120px square module. Content blocks occupy 2x3, 3x3, or 4x2 module arrangements, with consistent 24px gutters that create the "breathing corridors" (*ma*) between sections. Unlike a standard 12-column grid, this system produces slightly asymmetric compositions because tatami arrangements are inherently off-center -- the grid shifts 60px right of viewport center, creating a subtle but perceptible left-margin emphasis.

- **Z-Depth Layering:** Content exists on three distinct depth planes, achieved through parallax displacement, shadow scale, and opacity shifts. **Plane 0 (Background):** Deep jewel-toned gradient fields and subtle geometric patterns at 15% opacity. **Plane 1 (Content):** Primary text and isometric illustrations, casting 8px directional shadows onto Plane 0. **Plane 2 (Interactive):** Hover-activated elements, tooltips, and the navigation strip, which float above Plane 1 with 16px shadows and slight scale increase (1.02x). Scroll position determines which plane receives focus, with unfocused planes reducing to 60% opacity.

- **Vertical Rhythm via Golden Sections:** Section heights follow golden ratio proportions (1:1.618). If the hero is 100vh, the next major section is 61.8vh, the next is 38.2vh, then 23.6vh for a detail strip, before resetting to a new 100vh section. This creates a natural deceleration rhythm -- grand statement, elaboration, detail, pause, new grand statement.

- **No Horizontal Rules or Dividers:** Sections are separated solely by color-temperature shifts in the background gradient and by the depth-layering system. A transition from sapphire to amethyst signals a new content domain. No lines, no borders, no visual noise.

## Typography and Palette

**Typography:**

- **Display / Headlines:** "Josefin Sans" (Google Fonts) -- a geometric sans-serif with elegant, vintage Scandinavian-meets-Japanese proportions. Its tall x-height and optically monospaced feel give it the precision of technical documentation while its slightly Art Deco curves prevent sterility. Used at 3.5rem-6rem for the hero headline, 2rem-3rem for section titles. Weight: 700 for primary display, 300 (Light) for secondary headings to create dramatic weight contrast. Letter-spacing: +0.08em for section labels (creating the wide-tracked technical aesthetic), -0.01em for hero text at large sizes. Text-transform: uppercase for section labels, sentence case for hero.

- **Body / Explanatory Text:** "Work Sans" (Google Fonts) -- a grotesque-adjacent geometric sans-serif optimized for screen readability at body sizes. Its open apertures and low stroke contrast make it comfortable for extended reading against dark jewel-toned backgrounds. Used at 1rem-1.125rem for body text, 0.875rem for captions and metadata. Weight: 400 for body, 500 for emphasis, 600 for inline code labels. Line-height: 1.75 for body text (generous leading for dark-background readability), 1.5 for captions. Color: Pearl White (#E8E4DF) on dark backgrounds, ensuring AAA contrast against all jewel-tone background values.

- **Code / Technical Notation:** "IBM Plex Mono" (Google Fonts) -- a monospace typeface with humanist proportions and a warmth that distinguishes it from the clinical feel of Fira Code or Source Code Pro. Used for inline code references, terminal-style labels, and the navigation icon labels. Size: 0.875rem for inline code, 0.8125rem for metadata. Weight: 400. A subtle 1px left-border in Topaz Gold (#D4A841) distinguishes code blocks from body text. Background: a 4% lighter tint of whatever jewel tone occupies the current section background.

**Palette:**

The palette draws from Japanese jewel-tone traditions (*hosseki-shoku*) -- the deep, luminous colors found in lacquerware, cloisonne enamel, and silk obi fabrics:

| Role | Name | Hex | Usage |
|------|------|-----|-------|
| Primary Background | Midnight Sapphire | #0B1D3A | Hero section, primary content areas |
| Secondary Background | Emperor Amethyst | #2D1B4E | Alternate sections, code block backgrounds |
| Tertiary Background | Forest Malachite | #0A2E2A | Accent sections, footer region |
| Accent / Interactive | Topaz Gold | #D4A841 | Links, hover states, active indicators, code borders |
| Accent Secondary | Cinnabar Vermilion | #C44536 | Error states, critical highlights, decorative accents |
| Text Primary | Pearl White | #E8E4DF | Body text, headings on dark backgrounds |
| Text Secondary | Silver Mist | #9A9B9E | Captions, metadata, secondary labels |
| Depth Shadow | Obsidian | #06101F | Shadows on Plane 0, deep gradient terminus |

**Gradient Strategy:** Backgrounds transition between jewel tones using 180-degree linear gradients with a 40% overlap zone where colors blend through a desaturated midpoint (preventing muddy mixing). The hero gradient runs from Midnight Sapphire (#0B1D3A) at top to Obsidian (#06101F) at bottom. Section transitions shift the gradient origin color: Sapphire > Amethyst > Malachite > Sapphire (cycling).

## Imagery and Motifs

**Isometric Icon System:**

The primary visual language is a library of isometric technical illustrations rendered in a distinctive flat-jewel style. These are not generic isometric clip art; they are constructed as CSS-only or inline SVG compositions using precisely angled parallelograms (30-degree isometric projection) filled with jewel-tone gradients and accented with Topaz Gold (#D4A841) edge highlights.

Each illustration depicts a conceptual "workspace object":
- **Isometric Monitor:** A tilted screen showing abstract code lines (thin horizontal bars in varying lengths and opacities), resting on a minimal stand. The screen surface reflects a subtle gradient from Sapphire to Amethyst.
- **Isometric Book Stack:** Three stacked volumes in Malachite, Amethyst, and Sapphire, with gold-foil edge detail (1px Topaz Gold lines on the visible page edges). The top book is slightly offset, as if recently consulted.
- **Isometric Toolbox:** An open container showing organized compartments, each holding a geometric shape representing a different tool/technology. Rendered with visible internal depth shadows.
- **Isometric Window Frames:** Floating rectangular panels at different depths, connected by thin gold lines suggesting data flow or dependency relationships. These serve as section dividers.

All isometric elements share a consistent 30-degree angle, 2px stroke weight in Topaz Gold for edges, and jewel-tone gradient fills that match their containing section's background color family.

**Tilt-3D Interaction Pattern:**

Interactive elements respond to cursor proximity with a CSS `perspective` + `rotateX/rotateY` transform that tilts the element toward the cursor, creating a physical "card in hand" sensation. The tilt range is constrained to +/-8 degrees to maintain elegance (no wild wobbling). The tilt applies to:
- Isometric illustration containers (adding parallax depth to the flat isometric art)
- Navigation icon buttons (the vertical nav strip)
- Code block containers (subtle 2-3 degree tilt only)
- Section heading blocks

The tilt effect uses `will-change: transform` and a 200ms CSS transition with `cubic-bezier(0.33, 1, 0.68, 1)` easing for a smooth, weighted feel -- like tilting a lacquered tray, not flipping a playing card.

**Layered-Depth Motifs:**

Background layers contain subtle geometric patterns that reinforce the depth system:
- **Plane 0:** A sparse grid of thin lines (0.5px, Pearl White at 6% opacity) at 30-degree isometric angles, creating an architectural blueprint texture that's felt more than seen.
- **Plane 0.5 (Floating):** Occasional isometric wireframe shapes (cubes, hexagonal prisms) drift slowly across the background at 8% opacity, moving at 0.3px/second. These are pure CSS animations on `<div>` elements with `border` styling -- no images or canvas required.
- **Decorative Corners:** Each major section features a small isometric corner ornament in the top-right: a cluster of three nested squares in isometric projection, rendered in Topaz Gold at 20% opacity. This motif functions like a traditional Japanese *kamon* (family crest) -- a recurring identity mark.

**No Photography:** The site uses zero photographic imagery. All visuals are geometric, constructed, and systematic. This reinforces the tech-tutorial tone and avoids the generic stock-photo aesthetic that dominates the existing portfolio.

## Prompts for Implementation

**Full-Screen Narrative Experience:**

The site opens to a full-viewport field of Midnight Sapphire (#0B1D3A). After a 0.4-second stillness, the isometric grid lines (Plane 0 background pattern) begin drawing themselves from the viewport center outward, using `stroke-dashoffset` animation over 1.8 seconds. The lines extend in six directions following the isometric angle system (0, 30, 150, 180, 210, 330 degrees), creating a crystalline expansion pattern.

At t=1.2s (while the grid is still drawing), the hero's isometric illustration -- a single large monitor showing abstract code -- begins assembling itself. Each parallelogram face of the isometric object fades in sequentially (left face, top face, right face, screen content), with 150ms stagger between faces. Each face enters with a 12-degree Y-axis rotation that settles to 0 (the tilt-3d motif used as an entrance animation).

At t=2.0s, the headline text types itself character by character in Josefin Sans 700, 5rem, Topaz Gold (#D4A841). Not a crude typewriter effect with a blinking cursor, but a refined reveal: each character scales from 0.8 to 1.0 and fades from 0% to 100% opacity with a 40ms stagger, creating a "gold leaf being laid down" impression. No cursor element at all.

At t=3.0s, a single-line subtitle in Work Sans 400, 1.125rem, Pearl White (#E8E4DF) fades in over 600ms with a 20px upward translate.

At t=3.5s, a small downward-pointing chevron in Topaz Gold pulses gently at the bottom of the viewport (opacity oscillating between 40% and 80% on a 2-second cycle), indicating scrollable content below.

**Scroll Behavior:**

Scrolling is the primary navigation mechanism. The vertical navigation strip (left edge) appears at scroll position > 10vh, sliding in from the left with a 300ms ease-out transition. It remains fixed for the duration of the visit.

Each section transition uses a **color-temperature morph**: as the user scrolls past a section boundary, the background gradient hue shifts over 200px of scroll distance. This is achieved via CSS custom properties (`--bg-hue-start`, `--bg-hue-end`) updated by a lightweight scroll observer (IntersectionObserver with threshold array [0, 0.25, 0.5, 0.75, 1.0]). The transition feels like walking between rooms in a jewel-toned gallery -- the light changes, not the structure.

**Tilt-3D Implementation:**

```
Element.addEventListener('mousemove', (e) => {
  const rect = element.getBoundingClientRect();
  const centerX = rect.left + rect.width / 2;
  const centerY = rect.top + rect.height / 2;
  const rotateY = ((e.clientX - centerX) / (rect.width / 2)) * 8;
  const rotateX = ((centerY - e.clientY) / (rect.height / 2)) * 8;
  element.style.transform = `perspective(800px) rotateX(${rotateX}deg) rotateY(${rotateY}deg)`;
});
```

Apply to all `.tiltable` containers. On `mouseleave`, transition back to `rotateX(0) rotateY(0)` with the cubic-bezier easing. On touch devices, tilt responds to device orientation (DeviceOrientationEvent) with reduced range (+/-4 degrees).

**Section Content Structure:**

Each content section follows the Tatami Grid and contains:
1. A section label (IBM Plex Mono, 0.75rem, uppercase, letter-spacing +0.2em, Topaz Gold, positioned at the left margin of the tatami grid)
2. A section heading (Josefin Sans 300, 2.5rem, Pearl White)
3. Body content in Work Sans 400, arranged in 1-2 column layouts within the tatami module system
4. One isometric illustration per section, positioned at the grid's right-margin area, with tilt-3d interaction enabled

**AVOID:** CTA-heavy layouts, pricing blocks, stat-grids, testimonial carousels, hamburger menus, cookie banners, social media icons, stock photography, rounded-corner card grids, gradient text effects, drop shadows on text, parallax scrolling on images (parallax is reserved for the depth-layering system only).

**BIAS TOWARD:** Full-screen color immersion, typographic hierarchy as primary wayfinding, isometric illustrations as the sole visual content, scroll-driven narrative progression, jewel-tone color as emotional architecture.

## Uniqueness Notes

**Differentiators from other designs:**

1. **Zero-Photography Isometric Visual System:** While 72% of existing designs rely on photography and 94% use minimal imagery defaults, miris.works uses exclusively constructed isometric illustrations in jewel-tone gradients. Every visual element is geometric, systematic, and rendered via CSS/SVG. No design in the portfolio combines isometric projection with jewel-tone color theory as its primary visual language.

2. **Japanese-Minimal Structure with Jewel-Tone Richness:** The japanese-minimal aesthetic appears in 0% of existing designs. Rather than the expected white/neutral palette of Japanese minimalism, this design applies the spatial philosophy of *ma* and tatami proportional grids to deep sapphire, amethyst, and malachite backgrounds -- creating a novel fusion that is structurally minimal but chromatically maximal.

3. **Tilt-3D as Primary Interaction Metaphor:** While tilt-3d appears in only 3% of designs and is typically used as a minor hover effect, here it is the defining interaction pattern -- applied systematically to illustrations, navigation, code blocks, and entrance animations. The tilt transforms the flat isometric art into pseudo-3D objects that respond to the cursor like physical artifacts on a desk.

4. **Tatami Proportional Grid (Non-Centered Layout):** 99% of existing designs use centered layouts. The tatami grid shifts 60px right of center and uses proportional module arrangements derived from traditional Japanese room planning. This produces subtle asymmetry that feels intentional and crafted rather than broken or experimental.

5. **Tech-Tutorial Tone Without Terminal Aesthetic:** While tech-tutorial tone (1%) is extremely rare, the few existing implementations lean on terminal/console visual metaphors. miris.works achieves the instructional, authoritative tone through Japanese artisanal material metaphors -- gold-leaf typography, lacquerware color depth, washi paper texture -- creating a tech documentation atmosphere that feels precious rather than utilitarian.

**Planned Seed:** aesthetic: japanese-minimal, layout: hero-dominant, typography: geometric-sans, palette: jewel-tones, patterns: tilt-3d, imagery: isometric-icons, motifs: layered-depth, tone: tech-tutorial

**Avoided Overused Patterns:** playful aesthetic (94%), minimal imagery (94%), centered layout (99%), scroll-triggered as primary pattern (97%), parallax as dominant motion (78%), warm palette default (100%), friendly tone (98%), mono typography dominance (99%), vintage motifs (82%). Every seed dimension was chosen from the bottom quartile of frequency distribution to maximize portfolio differentiation.
<!-- DESIGN STAMP
  timestamp: 2026-03-10T15:43:30
  domain: miris.works
  seed: dimension was chosen from the bottom quartile of frequency distribution to maximize portfolio differentiation
  aesthetic: miris.works channels the disciplined beauty of a Japanese computational atelier ...
  content_hash: 4a138a6e563c
-->