@michaelmusyoka/eng-os-kit 1.0.0

package/skills/signature-dark-ui/references/layout-and-motion.md

@@ -0,0 +1,1246 @@
+# Layout, motion and signature reference
+
+Contents: container system, animation philosophy and allowed motion, the signature element and where to use it, section and hero design, trust sections, dashboard and sidebar, KPI cards, mobile and responsive rules, accessibility, over-use warnings, visual density and depth, section dividers.
+
+# 11. CONTAINER SYSTEM
+
+Use a maximum content width around:
+
+```text
+1200px
+```
+
+with responsive horizontal padding.
+
+Desktop:
+
+```text
+20–32px
+```
+
+Mobile:
+
+```text
+16–20px
+```
+
+The reference consistently uses a roughly 1200px content frame.
+
+Content should feel aligned.
+
+Do not create multiple unrelated horizontal alignment systems.
+
+---
+
+# 25. ANIMATION PHILOSOPHY
+
+Animation should communicate:
+
+- state
+- hierarchy
+- interaction
+- loading
+- progress
+
+Animation should NOT exist simply because an animation library is available.
+
+Use motion as punctuation.
+
+Not as decoration everywhere.
+
+---
+
+# 26. DEFAULT MOTION SPEED
+
+Use:
+
+```css
+--transition:
+220ms cubic-bezier(0.4,0,0.2,1);
+```
+
+This matches the reference interaction rhythm.
+
+Suggested ranges:
+
+```text
+micro interaction: 150–220ms
+hover: 180–250ms
+component entrance: 300–500ms
+large reveal: 500–800ms
+data/progress animation: 500–800ms
+ambient animation: 2–6s
+```
+
+---
+
+# 27. ALLOWED ANIMATIONS
+
+Use:
+
+### Fade + translate
+
+```text
+opacity 0 → 1
+translateY(12px) → 0
+```
+
+### Scale entrance
+
+```text
+scale(.97) → 1
+```
+
+### Pulse
+
+For:
+
+- active indicators
+- live status
+- signature mark
+
+### Shimmer
+
+For:
+
+- promotional banners
+- loading states
+- rare premium highlights
+
+### Progress animation
+
+For:
+
+- metrics
+- bars
+- dashboards
+
+### Number counting
+
+For:
+
+- statistics
+- revenue
+- orders
+- percentages
+
+---
+
+# 28. ANIMATIONS TO AVOID
+
+Do not use:
+
+- constant floating cards
+- spinning cards
+- excessive parallax
+- giant blob animations
+- bouncing buttons
+- text constantly moving
+- excessive particle backgrounds
+- cursor-following effects everywhere
+- random rotations
+- exaggerated 3D
+- animation on every scroll event
+
+Those effects are strongly associated with generic AI-generated "premium" websites.
+
+---
+
+# 29. THE SIGNATURE COMPONENT
+
+## THE SIGNATURE SIGNAL
+
+Every website in this design family MUST contain a subtle recurring identifying component.
+
+This is not a logo replacement.
+
+It is the designer's fingerprint.
+
+Call it:
+
+**Signature Signal**
+
+The base visual should be:
+
+```text
+small luminous dot
++
+very subtle secondary ring/halo
++
+occasionally a tiny secondary pulse
+```
+
+Conceptually:
+
+```text
+      ·
+    (   )
+```
+
+The exact implementation can vary.
+
+It may be:
+
+- a glowing dot
+- a dot with a faint ring
+- a tiny orbital ring
+- a two-node signal
+- a micro-gradient mark
+
+But it must remain recognizable as the same family signature.
+
+---
+
+# 30. SIGNATURE SIGNAL APPEARANCE
+
+Base:
+
+```css
+.signature-signal {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--blue-bright);
+  box-shadow:
+    0 0 10px var(--blue-bright),
+    0 0 22px rgba(59,130,246,0.25);
+  position: relative;
+}
+```
+
+Optional ring:
+
+```css
+.signature-signal::after {
+  content: "";
+  position: absolute;
+  inset: -5px;
+  border: 1px solid rgba(96,165,250,0.18);
+  border-radius: 50%;
+}
+```
+
+Optional animation:
+
+```css
+animation: signaturePulse 3s ease-in-out infinite;
+```
+
+But keep the animation extremely subtle.
+
+---
+
+# 31. WHERE TO USE THE SIGNATURE
+
+Do NOT put the signature everywhere.
+
+Use it in approximately 3–5 strategic locations.
+
+Possible placements:
+
+### 1. Brand mark
+
+Next to the product/company name.
+
+### 2. Footer
+
+As a tiny designer fingerprint.
+
+### 3. Section transition
+
+A small signal at the beginning/end of a major section.
+
+### 4. Loading state
+
+The signature becomes the loading indicator.
+
+### 5. Empty state
+
+A quiet version of the signature.
+
+### 6. Dashboard status
+
+A tiny "live" indicator.
+
+### 7. Favicon/app icon
+
+If appropriate.
+
+The signature should be recognizable only after someone has seen several products.
+
+That is the point.
+
+---
+
+# 32. SIGNATURE SHOULD NEVER BECOME DECORATION NOISE
+
+Do not:
+
+- put it beside every heading
+- put it in every card
+- animate it constantly
+- make it huge
+- make it the center of attention
+- turn it into a giant logo
+
+The reaction should be:
+
+> "There is something consistent about these interfaces."
+
+Not:
+
+> "Why is there a glowing dot everywhere?"
+
+---
+
+# 33. SIGNATURE VARIATION
+
+The same signature can adapt to the product.
+
+Examples:
+
+### Marketing website
+Glowing dot + ring.
+
+### Dashboard
+Dot becomes live-status indicator.
+
+### Developer tool
+Dot becomes a small system-status signal.
+
+### E-commerce
+Dot becomes a subtle product-status indicator.
+
+### SaaS
+Dot becomes a workspace/status marker.
+
+### Mobile application
+Dot becomes part of the app icon.
+
+The underlying geometry should remain recognizable.
+
+---
+
+# 34. SECTION DESIGN
+
+Avoid creating every section as:
+
+```text
+heading
+paragraph
+three cards
+```
+
+That is a major source of generic AI aesthetics.
+
+Instead vary composition.
+
+Use:
+
+- split layouts
+- asymmetric grids
+- feature panels
+- data visualizations
+- horizontal strips
+- large single-feature cards
+- comparison layouts
+- editorial sections
+- overlapping elements
+- compact metrics
+- interactive demonstrations
+- visual timelines
+- workflow diagrams
+- product previews
+
+The design language should stay consistent even when the composition changes.
+
+---
+
+# 35. HERO SECTIONS
+
+A hero should generally contain:
+
+### Left
+
+- small status/badge
+- large heading
+- concise supporting text
+- primary action
+- secondary action
+- trust/proof if useful
+
+### Right
+
+A meaningful visual.
+
+Do not automatically put a giant abstract gradient blob on the right.
+
+Prefer:
+
+- product preview
+- dashboard
+- interactive component
+- device mockup
+- data visualization
+- contextual UI
+- workflow visualization
+
+The reference hero follows a text/product-preview split and uses compact badges, gradient heading emphasis, feature chips, CTAs, and social proof.
+
+---
+
+# 36. HERO VISUALS MUST REPRESENT THE PRODUCT
+
+If the website is for:
+
+### Analytics software
+
+Show analytics.
+
+### Deployment platform
+
+Show deployment infrastructure.
+
+### CRM
+
+Show contacts, pipelines, activity.
+
+### E-commerce
+
+Show products, orders, revenue.
+
+### Developer tool
+
+Show code/configuration/system state.
+
+Do not use an unrelated abstract 3D object.
+
+The visual should explain what the product actually does.
+
+---
+
+# 37. TRUST SECTIONS
+
+Trust should use compact visual modules.
+
+Examples:
+
+```text
+[icon] Secure
+       Enterprise-grade security
+```
+
+or:
+
+```text
+[icon] 99.9%
+       Uptime
+```
+
+The reference uses compact bordered trust cards with small icon containers.
+
+Avoid giant "trusted by" logos consuming an entire viewport.
+
+---
+
+# 38. DASHBOARD DESIGN
+
+Dashboard interfaces should feel dense but breathable.
+
+Preferred structure:
+
+```text
+SIDEBAR
+    |
+    +-- top-level navigation
+    |
+    +-- contextual sections
+    |
+    +-- account/settings
+    |
+MAIN
+    |
+    +-- page heading
+    +-- contextual action
+    +-- KPI row
+    +-- primary visualization
+    +-- secondary visualizations
+    +-- tables/details
+```
+
+The reference dashboard uses a dark sidebar, compact navigation, stat cards, charts, tables, badges, and responsive mobile navigation.
+
+---
+
+# 39. DASHBOARD SIDEBAR
+
+Sidebar:
+
+- dark
+- narrow
+- fixed/sticky on desktop
+- subtle border
+- compact navigation
+- muted inactive states
+- blue-highlighted active state
+
+Do not make the sidebar visually louder than the content.
+
+---
+
+# 40. KPI CARDS
+
+A KPI card should contain:
+
+```text
+small label
+large value
+supporting metadata
+optional trend
+optional icon
+```
+
+Example:
+
+```text
+TOTAL REVENUE
+
+KES 184,920
+
++12.4% this month
+```
+
+Use color strategically.
+
+The reference dashboard uses colored KPI values and subtle per-card border accents rather than making every card brightly colored.
+
+---
+
+# 45. MOBILE DESIGN
+
+Mobile must be treated as a real layout.
+
+Do not simply compress desktop.
+
+At approximately 900px:
+
+- simplify multi-column layouts
+- stack complex panels
+
+At approximately 700px:
+
+- hero becomes single-column
+- navigation collapses
+- dashboard cards become smaller
+- grids become 1–2 columns
+- footer simplifies
+- modal padding decreases
+
+This follows the reference's responsive behavior.
+
+---
+
+# 46. MOBILE NAVIGATION
+
+Desktop:
+
+```text
+horizontal navigation
+```
+
+Mobile:
+
+```text
+hamburger
+↓
+full navigation panel/drawer
+```
+
+The reference explicitly switches from desktop navigation to a hamburger/mobile navigation pattern.
+
+The mobile navigation should feel like the same product, not a separate design.
+
+---
+
+# 47. RESPONSIVE PRINCIPLE
+
+At every breakpoint ask:
+
+> "What information is most important?"
+
+Then preserve that information.
+
+Do not simply reduce everything proportionally.
+
+Mobile should prioritize:
+
+1. primary heading
+2. primary action
+3. critical information
+4. essential navigation
+5. supporting content
+
+---
+
+# 50. ACCESSIBILITY
+
+Do not sacrifice usability for aesthetics.
+
+Maintain:
+
+- readable contrast
+- visible focus states
+- keyboard navigation
+- accessible labels
+- reduced-motion support
+- touch-friendly targets
+- semantic HTML
+
+Include:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+---
+
+# 51. DO NOT OVERUSE ROUNDED CARDS
+
+This is one of the most important anti-"vibe coded" rules.
+
+Do not make every section:
+
+```text
+┌──────────────────────┐
+│                      │
+│       CARD           │
+│                      │
+└──────────────────────┘
+```
+
+Instead mix:
+
+- cards
+- full-width sections
+- dividers
+- inline content
+- edge-to-edge visual blocks
+- grids
+- panels
+- tables
+- floating components
+
+The visual system should create hierarchy through **composition**, not simply through cards.
+
+---
+
+# 52. DO NOT OVERUSE GRADIENT TEXT
+
+Only use gradient text for strategically important words.
+
+Usually:
+
+```text
+one phrase
+```
+
+not:
+
+```text
+every heading
+every button
+every label
+```
+
+---
+
+# 53. DO NOT OVERUSE GLOW
+
+Glow should mean:
+
+> "Pay attention."
+
+If everything glows, nothing has emphasis.
+
+Use strong glow only on:
+
+- primary CTA
+- active status
+- Signature Signal
+- selected/highlighted component
+- major hero accent
+
+---
+
+# 54. DO NOT USE GENERIC AI DECORATION
+
+Absolutely avoid automatically generating:
+
+- random glowing blobs
+- abstract 3D spheres
+- floating glass panels
+- excessive stars
+- random particles
+- generic gradient mesh
+- huge neon rings
+- meaningless code snippets
+- meaningless dashboard screenshots
+- decorative lines with no compositional purpose
+
+Every visual element must have a reason to exist.
+
+---
+
+# 55. VISUAL DENSITY
+
+The interface should feel sophisticated because it contains **useful information**, not because it contains lots of decoration.
+
+Use compact secondary text.
+
+Use meaningful metadata.
+
+Use small status indicators.
+
+Use structured information.
+
+This is especially important for dashboards and applications.
+
+The reference dashboard demonstrates this through KPI grids, chart panels, funnels, tables, and payment breakdowns.
+
+---
+
+# 56. VISUAL DEPTH
+
+Create depth using four layers:
+
+```text
+Layer 0
+Base background
+
+Layer 1
+Surface
+
+Layer 2
+Card
+
+Layer 3
+Focused/featured element
+```
+
+Use:
+
+- color difference
+- border
+- shadow
+- slight glow
+
+Do not rely on giant shadows.
+
+---
+
+# 57. SECTION DIVIDERS
+
+Use extremely subtle dividers.
+
+Example:
+
+```css
+height: 1px;
+background: var(--border);
+```
+
+The reference uses a simple 1px low-opacity divider system.
+
+Do not use decorative ornamental dividers everywhere.
+
+---
+
+# 58. PROMOTIONAL ELEMENTS
+
+If the product requires urgency or promotional banners, they can use animated gradients.
+
+Reference example:
+
+```css
+background:
+  linear-gradient(
+    90deg,
+    #1d4ed8 0%,
+    #0891b2 50%,
+    #1d4ed8 100%
+  );
+
+background-size: 200% 100%;
+animation: bannerShimmer 3s linear infinite;
+```
+
+
+
+But only use this treatment when the content actually warrants urgency.
+
+---
+
+# 59. CONTENT + DESIGN RELATIONSHIP
+
+The design should adapt to the content.
+
+If the content is:
+
+### Technical
+Increase information density.
+
+### Consumer
+Increase whitespace and visual storytelling.
+
+### Financial
+Emphasize numbers and hierarchy.
+
+### Developer-focused
+Use system-oriented panels and code/data treatments.
+
+### Marketing
+Increase visual contrast and CTA hierarchy.
+
+### Admin
+Prioritize information density.
+
+The **visual language stays consistent**, while the composition changes.
+
+---
+
+# 60. THE "SAME DESIGNER" TEST
+
+After generating the website, ask:
+
+> "If I put this beside the reference websites, would I believe they were designed by the same person?"
+
+The answer should be yes.
+
+But also ask:
+
+> "Could someone mistake this for a copy of the reference website?"
+
+The answer should be no.
+
+This distinction is critical.
+
+---
+
+# 61. ANTI-VIBE-CODE CHECKLIST
+
+Before considering the design finished, verify:
+
+- [ ] No random gradients
+- [ ] No excessive glassmorphism
+- [ ] No excessive rounded cards
+- [ ] No giant decorative blobs
+- [ ] No unnecessary animation
+- [ ] No generic SaaS dashboard composition
+- [ ] No default Tailwind appearance
+- [ ] No excessive shadows
+- [ ] No excessive glow
+- [ ] No 4–5 font families
+- [ ] No random colors
+- [ ] No inconsistent border radii
+- [ ] No arbitrary spacing everywhere
+- [ ] No decorative elements without purpose
+- [ ] No huge empty areas created merely to look "premium"
+- [ ] No mobile layout that simply squashes desktop
+
+---
+
+# 62. SIGNATURE SYSTEM CHECKLIST
+
+Every new website must contain:
+
+- [ ] Signature Signal somewhere visible
+- [ ] Signature Signal used subtly
+- [ ] Same underlying geometry
+- [ ] Same luminous quality
+- [ ] Product-specific adaptation
+- [ ] No excessive repetition
+- [ ] Signature appears in at least 2 meaningful contexts
+- [ ] Signature is recognizable across products
+
+---
+
+# 63. COMPONENT CREATION RULE
+
+When the product requires a component that does not exist in the reference:
+
+Do not copy an existing component blindly.
+
+Instead derive the new component from the design primitives:
+
+```text
+color
++
+spacing
++
+radius
++
+border
++
+shadow
++
+typography
++
+motion
+```
+
+For example, if creating a new notification component:
+
+```text
+dark surface
++
+subtle border
++
+small radius
++
+compact typography
++
+small semantic icon
++
+controlled accent
++
+220ms interaction
+```
+
+It should look native to the system.
+
+---
+
+# 64. COMPONENT HIERARCHY
+
+Every component must answer:
+
+### What is it?
+
+Typography.
+
+### Where is it?
+
+Spacing.
+
+### What layer is it?
+
+Surface/background.
+
+### Is it interactive?
+
+Hover/focus behavior.
+
+### Is it important?
+
+Color/glow hierarchy.
+
+### Does it move?
+
+Animation only if useful.
+
+---
+
+# 65. CSS ARCHITECTURE
+
+If using plain CSS, create global tokens first.
+
+Example:
+
+```css
+:root {
+  /* backgrounds */
+  --bg-base: #060914;
+  --bg-surface: #0d1225;
+  --bg-card: #111827;
+  --bg-card-hover: #151f35;
+
+  /* borders */
+  --border: rgba(99,130,255,.12);
+  --border-bright: rgba(99,130,255,.30);
+
+  /* brand */
+  --primary: #3b82f6;
+  --primary-bright: #60a5fa;
+  --primary-deep: #1d4ed8;
+  --accent: #06b6d4;
+  --primary-glow: rgba(59,130,246,.35);
+
+  /* text */
+  --text-primary: #f1f5f9;
+  --text-secondary: #94a3b8;
+  --text-muted: #4b5563;
+
+  /* semantic */
+  --success: #10b981;
+  --warning: #f59e0b;
+  --danger: #ef4444;
+
+  /* geometry */
+  --radius-sm: 8px;
+  --radius: 14px;
+  --radius-lg: 20px;
+
+  /* effects */
+  --shadow-card: 0 4px 32px rgba(0,0,0,.45);
+  --shadow-glow: 0 0 32px rgba(59,130,246,.25);
+
+  /* motion */
+  --transition: 220ms cubic-bezier(.4,0,.2,1);
+}
+```
+
+---
+
+# 66. IF USING TAILWIND
+
+Do not simply use Tailwind's defaults.
+
+Create the equivalent design tokens in the Tailwind theme.
+
+Do not allow arbitrary Tailwind values to become the visual system.
+
+The uploaded `globals.css` currently contains a conventional light Shadcn/Tailwind-style variable foundation, which is visually disconnected from the dark reference system.
+
+If replacing that system:
+
+- preserve application functionality
+- preserve existing class contracts where possible
+- replace visual primitives systematically
+- avoid mixing the old light design tokens with the new dark system
+
+---
+
+# 67. GLOBAL CSS PRIORITY
+
+When styling an existing application:
+
+### DO
+
+1. Inspect the existing DOM/component structure.
+2. Understand the current class names.
+3. Preserve functionality.
+4. Preserve semantic meaning.
+5. Establish global tokens.
+6. Establish typography.
+7. Establish surfaces.
+8. Establish components.
+9. Establish responsive behavior.
+10. Add animation.
+11. Add Signature Signal.
+12. Perform a visual consistency pass.
+
+### DO NOT
+
+Rewrite application logic merely to make styling easier.
+
+Do not remove functionality.
+
+Do not change APIs.
+
+Do not change database behavior.
+
+Do not change business logic.
+
+Do not change routing unless explicitly requested.
+
+---
+
+# 68. IMPORTANT FOR LLMs STYLING EXISTING PROJECTS
+
+You are primarily changing the **visual system**.
+
+Do not unnecessarily modify:
+
+- JavaScript logic
+- API calls
+- database queries
+- authentication
+- data structures
+- business rules
+- component behavior
+- routes
+
+If a visual problem can be solved with CSS, solve it with CSS.
+
+If a component must be structurally changed for visual reasons, make the smallest structural change necessary.
+
+---
+
+# 69. DESIGN IMPLEMENTATION ORDER
+
+When styling a new application, work in this order:
+
+## Phase 1 — Foundation
+
+Implement:
+
+- CSS variables
+- reset
+- body
+- typography
+- base links
+- buttons
+- form controls
+- scrollbar
+- selection state
+
+## Phase 2 — Layout
+
+Implement:
+
+- container
+- grid
+- section spacing
+- responsive breakpoints
+- navigation
+- footer
+
+## Phase 3 — Surfaces
+
+Implement:
+
+- cards
+- panels
+- borders
+- shadows
+- backgrounds
+
+## Phase 4 — Content Components
+
+Implement:
+
+- badges
+- stats
+- tables
+- forms
+- charts
+- lists
+- feature blocks
+- modals
+
+## Phase 5 — Interaction
+
+Implement:
+
+- hover
+- focus
+- active
+- loading
+- transitions
+
+## Phase 6 — Motion
+
+Implement:
+
+- entrance animations
+- counters
+- progress animations
+- subtle ambient motion
+
+## Phase 7 — Signature
+
+Implement:
+
+- Signature Signal
+- signature variations
+- loading/empty-state usage
+
+## Phase 8 — Refinement
+
+Check:
+
+- spacing
+- typography
+- visual hierarchy
+- responsive behavior
+- animation
+- accessibility
+- consistency
+
+---
+
+# 70. VISUAL QA
+
+After styling, inspect the entire site as a single system.
+
+Ask:
+
+### Color
+
+Is the blue/cyan accent too dominant?
+
+### Typography
+
+Are headings clearly stronger than body copy?
+
+### Cards
+
+Are there too many?
+
+### Glow
+
+Is glow being used as emphasis or decoration?
+
+### Motion
+
+Does animation communicate something?
+
+### Spacing
+
+Do sections breathe consistently?
+
+### Responsive
+
+Does mobile feel intentionally designed?
+
+### Signature
+
+Can the visual fingerprint be recognized?
+
+### Originality
+
+Does the site feel like a member of the design family without looking copied?
+
+---
+
+# 71. FINAL QUALITY STANDARD
+
+The finished product should feel like:
+
+> A serious digital product designed by a small, highly opinionated design studio.
+
+Not:
+
+> A website generated from a prompt.
+
+That distinction should guide every decision.
+
+---
+
+# 72. MASTER LLM INSTRUCTION
+
+When given an existing website and asked to apply this style, use the following operating instruction:
+
+**"Study the existing application structure first. Do not redesign its functionality. Apply the Signature Dark Interface design system as a visual language, not as a template. Preserve the product's information architecture where appropriate, but redesign weak compositions when necessary. Use dark navy surfaces, restrained blue/cyan illumination, subtle borders, controlled card elevation, Space Grotesk for display typography, DM Sans for interface/body typography, compact spacing, deliberate hierarchy, restrained gradients, and purposeful motion. Create visual depth through layers rather than excessive glassmorphism. Use animation to communicate state and interaction rather than decoration. Avoid generic AI aesthetics such as giant gradient blobs, excessive rounded cards, excessive glow, excessive glass, random gradients, meaningless floating elements, and over-animated interfaces. Every component must appear to belong to one coherent visual system. Introduce the Signature Signal as a subtle recurring designer fingerprint, adapting its placement to the product while keeping its underlying geometry recognizable. The result must feel like the same designer created the site, but it must remain original to the product."**
+
+---
+
+# 73. FINAL NON-NEGOTIABLE RULE
+
+**Do not optimize for "wow" in the first five seconds.**
+
+Optimize for:
+
+**recognition → hierarchy → clarity → trust → interaction → polish.**
+
+The interface should become more impressive the longer someone uses it.
+