docs: redesign README with visual layout and SVG assets (#107)

sofq · web-flow · commit 7d6b6dc8f78c · 2026-04-05T17:24:33.000+07:00
## Summary
- Redesign README with SVG banner (light/dark mode), feature grid, and
section dividers
- Add collapsible install section, table of contents, and back-to-top
links
- Reorganize content for better scannability with search, raw API, and
error contract sections

## Test plan
- [ ] Verify banner renders correctly in both light and dark GitHub
themes
- [ ] Confirm all SVG assets load from `.github/readme/`
- [ ] Check collapsible sections expand/collapse properly
- [ ] Validate badge links point to correct URLs
diff --git a/.github/readme/banner-dark.svg b/.github/readme/banner-dark.svg
@@ -0,0 +1,117 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 280" width="900" height="280">
+  <defs>
+    <!-- Dark gradient mesh background -->
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#0f172a"/>
+      <stop offset="40%" stop-color="#1e1b4b"/>
+      <stop offset="100%" stop-color="#0c4a6e"/>
+    </linearGradient>
+    <radialGradient id="glow1" cx="15%" cy="50%" r="40%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#7c3aed" stop-opacity="0.25"/>
+      <stop offset="100%" stop-color="#7c3aed" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="glow2" cx="75%" cy="30%" r="35%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#06b6d4" stop-opacity="0.18"/>
+      <stop offset="100%" stop-color="#06b6d4" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="glow3" cx="90%" cy="80%" r="25%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#f59e0b" stop-opacity="0.12"/>
+      <stop offset="100%" stop-color="#f59e0b" stop-opacity="0"/>
+    </radialGradient>
+    <!-- Text gradient -->
+    <linearGradient id="textGrad" x1="0%" y1="0%" x2="100%" y2="100%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#a78bfa"/>
+      <stop offset="50%" stop-color="#818cf8"/>
+      <stop offset="100%" stop-color="#67e8f9"/>
+    </linearGradient>
+    <!-- Accent line gradient -->
+    <linearGradient id="accentLine" x1="0%" y1="0%" x2="100%" y2="0%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#a78bfa" stop-opacity="0"/>
+      <stop offset="30%" stop-color="#a78bfa"/>
+      <stop offset="70%" stop-color="#22d3ee"/>
+      <stop offset="100%" stop-color="#22d3ee" stop-opacity="0"/>
+    </linearGradient>
+    <!-- Noise filter -->
+    <filter id="noise" color-interpolation-filters="linearRGB" x="-20%" y="-20%" width="140%" height="140%">
+      <feTurbulence type="fractalNoise" baseFrequency="0.65" numOctaves="3" stitchTiles="stitch" result="n"/>
+      <feBlend in="SourceGraphic" in2="n" mode="overlay" result="blend"/>
+      <feComponentTransfer in="blend">
+        <feFuncA type="linear" slope="0.04"/>
+      </feComponentTransfer>
+      <feComposite in2="SourceGraphic" operator="in"/>
+      <feMerge>
+        <feMergeNode in="SourceGraphic"/>
+        <feMergeNode/>
+      </feMerge>
+    </filter>
+    <!-- Dot pattern -->
+    <pattern id="dots" width="24" height="24" patternUnits="userSpaceOnUse">
+      <circle cx="12" cy="12" r="1" fill="#a78bfa" opacity="0.06"/>
+    </pattern>
+  </defs>
+
+  <style>
+    @keyframes slideIn {
+      from { opacity: 0; transform: translateX(-20px); }
+      to { opacity: 1; transform: translateX(0); }
+    }
+    @keyframes fadeUp {
+      from { opacity: 0; transform: translateY(10px); }
+      to { opacity: 1; transform: translateY(0); }
+    }
+    @keyframes accentDraw {
+      from { stroke-dashoffset: 500; }
+      to { stroke-dashoffset: 0; }
+    }
+    @keyframes pulse {
+      0%, 100% { opacity: 0.3; }
+      50% { opacity: 0.7; }
+    }
+    .title { animation: slideIn 0.6s ease-out both; }
+    .tagline { animation: fadeUp 0.5s ease-out 0.3s both; }
+    .accent { animation: accentDraw 1s ease-out 0.5s both; stroke-dasharray: 500; }
+    .dot-float { animation: pulse 3s ease-in-out infinite; }
+  </style>
+
+  <!-- Background -->
+  <rect width="900" height="280" fill="url(#bg)"/>
+  <rect width="900" height="280" fill="url(#glow1)"/>
+  <rect width="900" height="280" fill="url(#glow2)"/>
+  <rect width="900" height="280" fill="url(#glow3)"/>
+  <rect width="900" height="280" fill="url(#dots)"/>
+
+  <!-- Diagonal energy lines -->
+  <line x1="580" y1="0" x2="680" y2="280" stroke="#a78bfa" stroke-width="0.5" opacity="0.12"/>
+  <line x1="620" y1="0" x2="720" y2="280" stroke="#22d3ee" stroke-width="0.5" opacity="0.12"/>
+  <line x1="660" y1="0" x2="760" y2="280" stroke="#a78bfa" stroke-width="0.5" opacity="0.07"/>
+  <line x1="700" y1="0" x2="800" y2="280" stroke="#22d3ee" stroke-width="0.5" opacity="0.07"/>
+
+  <!-- Floating geometric accents -->
+  <circle cx="720" cy="80" r="40" fill="none" stroke="#a78bfa" stroke-width="1" opacity="0.1" class="dot-float"/>
+  <circle cx="780" cy="180" r="25" fill="none" stroke="#22d3ee" stroke-width="1" opacity="0.12" class="dot-float" style="animation-delay: 1s"/>
+  <rect x="820" y="60" width="30" height="30" rx="4" fill="none" stroke="#f59e0b" stroke-width="1" opacity="0.12" transform="rotate(15, 835, 75)" class="dot-float" style="animation-delay: 2s"/>
+
+  <!-- Small scattered dots -->
+  <circle cx="650" cy="50" r="2" fill="#a78bfa" opacity="0.2" class="dot-float"/>
+  <circle cx="750" cy="140" r="2.5" fill="#22d3ee" opacity="0.2" class="dot-float" style="animation-delay: 0.5s"/>
+  <circle cx="830" cy="220" r="2" fill="#f59e0b" opacity="0.2" class="dot-float" style="animation-delay: 1.5s"/>
+  <circle cx="690" cy="230" r="1.5" fill="#a78bfa" opacity="0.12" class="dot-float" style="animation-delay: 2.5s"/>
+  <circle cx="860" cy="120" r="1.5" fill="#22d3ee" opacity="0.12" class="dot-float" style="animation-delay: 0.8s"/>
+
+  <!-- Main title "jr" -->
+  <g class="title">
+    <text x="100" y="145" font-family="'Segoe UI', system-ui, -apple-system, sans-serif" font-size="120" font-weight="800" fill="url(#textGrad)" letter-spacing="-4">jr</text>
+  </g>
+
+  <!-- Accent line under title -->
+  <line x1="95" y1="165" x2="595" y2="165" stroke="url(#accentLine)" stroke-width="2" class="accent"/>
+
+  <!-- Tagline -->
+  <g class="tagline">
+    <text x="105" y="200" font-family="'Segoe UI', system-ui, -apple-system, sans-serif" font-size="20" fill="#cbd5e1" font-weight="400" letter-spacing="0.5">The Jira CLI that speaks JSON</text>
+    <text x="105" y="228" font-family="'Segoe UI', system-ui, -apple-system, sans-serif" font-size="15" fill="#64748b" font-weight="400" letter-spacing="0.5">built for AI agents</text>
+  </g>
+
+  <!-- Amber accent dot -->
+  <circle cx="245" cy="150" r="5" fill="#f59e0b" opacity="0.5" class="dot-float"/>
+</svg>
diff --git a/.github/readme/banner.svg b/.github/readme/banner.svg
@@ -0,0 +1,117 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 280" width="900" height="280">
+  <defs>
+    <!-- Gradient mesh background -->
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#f8fafc"/>
+      <stop offset="40%" stop-color="#ede9fe"/>
+      <stop offset="100%" stop-color="#e0f2fe"/>
+    </linearGradient>
+    <radialGradient id="glow1" cx="15%" cy="50%" r="40%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#7c3aed" stop-opacity="0.15"/>
+      <stop offset="100%" stop-color="#7c3aed" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="glow2" cx="75%" cy="30%" r="35%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#06b6d4" stop-opacity="0.12"/>
+      <stop offset="100%" stop-color="#06b6d4" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="glow3" cx="90%" cy="80%" r="25%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#f59e0b" stop-opacity="0.1"/>
+      <stop offset="100%" stop-color="#f59e0b" stop-opacity="0"/>
+    </radialGradient>
+    <!-- Text gradient -->
+    <linearGradient id="textGrad" x1="0%" y1="0%" x2="100%" y2="100%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#7c3aed"/>
+      <stop offset="50%" stop-color="#6d28d9"/>
+      <stop offset="100%" stop-color="#4f46e5"/>
+    </linearGradient>
+    <!-- Accent line gradient -->
+    <linearGradient id="accentLine" x1="0%" y1="0%" x2="100%" y2="0%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#7c3aed" stop-opacity="0"/>
+      <stop offset="30%" stop-color="#7c3aed"/>
+      <stop offset="70%" stop-color="#06b6d4"/>
+      <stop offset="100%" stop-color="#06b6d4" stop-opacity="0"/>
+    </linearGradient>
+    <!-- Noise filter -->
+    <filter id="noise" color-interpolation-filters="linearRGB" x="-20%" y="-20%" width="140%" height="140%">
+      <feTurbulence type="fractalNoise" baseFrequency="0.65" numOctaves="3" stitchTiles="stitch" result="n"/>
+      <feBlend in="SourceGraphic" in2="n" mode="overlay" result="blend"/>
+      <feComponentTransfer in="blend">
+        <feFuncA type="linear" slope="0.03"/>
+      </feComponentTransfer>
+      <feComposite in2="SourceGraphic" operator="in"/>
+      <feMerge>
+        <feMergeNode in="SourceGraphic"/>
+        <feMergeNode/>
+      </feMerge>
+    </filter>
+    <!-- Dot pattern -->
+    <pattern id="dots" width="24" height="24" patternUnits="userSpaceOnUse">
+      <circle cx="12" cy="12" r="1" fill="#7c3aed" opacity="0.08"/>
+    </pattern>
+  </defs>
+
+  <style>
+    @keyframes slideIn {
+      from { opacity: 0; transform: translateX(-20px); }
+      to { opacity: 1; transform: translateX(0); }
+    }
+    @keyframes fadeUp {
+      from { opacity: 0; transform: translateY(10px); }
+      to { opacity: 1; transform: translateY(0); }
+    }
+    @keyframes accentDraw {
+      from { stroke-dashoffset: 500; }
+      to { stroke-dashoffset: 0; }
+    }
+    @keyframes pulse {
+      0%, 100% { opacity: 0.4; }
+      50% { opacity: 0.8; }
+    }
+    .title { animation: slideIn 0.6s ease-out both; }
+    .tagline { animation: fadeUp 0.5s ease-out 0.3s both; }
+    .accent { animation: accentDraw 1s ease-out 0.5s both; stroke-dasharray: 500; }
+    .dot-float { animation: pulse 3s ease-in-out infinite; }
+  </style>
+
+  <!-- Background -->
+  <rect width="900" height="280" fill="url(#bg)"/>
+  <rect width="900" height="280" fill="url(#glow1)"/>
+  <rect width="900" height="280" fill="url(#glow2)"/>
+  <rect width="900" height="280" fill="url(#glow3)"/>
+  <rect width="900" height="280" fill="url(#dots)"/>
+
+  <!-- Diagonal energy lines -->
+  <line x1="580" y1="0" x2="680" y2="280" stroke="#7c3aed" stroke-width="0.5" opacity="0.1"/>
+  <line x1="620" y1="0" x2="720" y2="280" stroke="#06b6d4" stroke-width="0.5" opacity="0.1"/>
+  <line x1="660" y1="0" x2="760" y2="280" stroke="#7c3aed" stroke-width="0.5" opacity="0.06"/>
+  <line x1="700" y1="0" x2="800" y2="280" stroke="#06b6d4" stroke-width="0.5" opacity="0.06"/>
+
+  <!-- Floating geometric accents -->
+  <circle cx="720" cy="80" r="40" fill="none" stroke="#7c3aed" stroke-width="1" opacity="0.08" class="dot-float"/>
+  <circle cx="780" cy="180" r="25" fill="none" stroke="#06b6d4" stroke-width="1" opacity="0.1" class="dot-float" style="animation-delay: 1s"/>
+  <rect x="820" y="60" width="30" height="30" rx="4" fill="none" stroke="#f59e0b" stroke-width="1" opacity="0.1" transform="rotate(15, 835, 75)" class="dot-float" style="animation-delay: 2s"/>
+
+  <!-- Small scattered dots -->
+  <circle cx="650" cy="50" r="2" fill="#7c3aed" opacity="0.15" class="dot-float"/>
+  <circle cx="750" cy="140" r="2.5" fill="#06b6d4" opacity="0.15" class="dot-float" style="animation-delay: 0.5s"/>
+  <circle cx="830" cy="220" r="2" fill="#f59e0b" opacity="0.15" class="dot-float" style="animation-delay: 1.5s"/>
+  <circle cx="690" cy="230" r="1.5" fill="#7c3aed" opacity="0.1" class="dot-float" style="animation-delay: 2.5s"/>
+  <circle cx="860" cy="120" r="1.5" fill="#06b6d4" opacity="0.1" class="dot-float" style="animation-delay: 0.8s"/>
+
+  <!-- Main title "jr" -->
+  <g class="title">
+    <text x="100" y="145" font-family="'Segoe UI', system-ui, -apple-system, sans-serif" font-size="120" font-weight="800" fill="url(#textGrad)" letter-spacing="-4">jr</text>
+  </g>
+
+  <!-- Accent line under title -->
+  <line x1="95" y1="165" x2="595" y2="165" stroke="url(#accentLine)" stroke-width="2" class="accent"/>
+
+  <!-- Tagline -->
+  <g class="tagline">
+    <text x="105" y="200" font-family="'Segoe UI', system-ui, -apple-system, sans-serif" font-size="20" fill="#475569" font-weight="400" letter-spacing="0.5">The Jira CLI that speaks JSON</text>
+    <text x="105" y="228" font-family="'Segoe UI', system-ui, -apple-system, sans-serif" font-size="15" fill="#94a3b8" font-weight="400" letter-spacing="0.5">built for AI agents</text>
+  </g>
+
+  <!-- Amber accent dot -->
+  <circle cx="245" cy="150" r="5" fill="#f59e0b" opacity="0.6" class="dot-float"/>
+</svg>
diff --git a/.github/readme/divider.svg b/.github/readme/divider.svg
@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 12" width="900" height="12">
+  <defs>
+    <linearGradient id="grad" x1="0%" y1="0%" x2="100%" y2="0%" color-interpolation="linearRGB">
+      <stop offset="0%" stop-color="#7c3aed" stop-opacity="0"/>
+      <stop offset="20%" stop-color="#7c3aed" stop-opacity="0.4"/>
+      <stop offset="50%" stop-color="#06b6d4" stop-opacity="0.5"/>
+      <stop offset="80%" stop-color="#f59e0b" stop-opacity="0.3"/>
+      <stop offset="100%" stop-color="#f59e0b" stop-opacity="0"/>
+    </linearGradient>
+  </defs>
+  <line x1="50" y1="6" x2="850" y2="6" stroke="url(#grad)" stroke-width="1.5" stroke-linecap="round"/>
+  <circle cx="450" cy="6" r="2.5" fill="#06b6d4" opacity="0.5"/>
+</svg>
diff --git a/.github/readme/icon-batch.svg b/.github/readme/icon-batch.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="#7c3aed" d="M12 0L3 7l1.63 1.27L12 14l7.36-5.73L21 7zm7.37 10.73L12 16.47l-7.38-5.73L3 12l9 7l9-7zm0 5L12 21.47l-7.38-5.73L3 17l9 7l9-7z"/></svg>
diff --git a/.github/readme/icon-schema.svg b/.github/readme/icon-schema.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="#7c3aed" d="m19.07 4.93l-1.41 1.41A8 8 0 0 1 20 12a8 8 0 0 1-8 8a8 8 0 0 1-8-8c0-4.08 3.05-7.44 7-7.93v2.02C8.16 6.57 6 9.03 6 12a6 6 0 0 0 6 6a6 6 0 0 0 6-6c0-1.66-.67-3.16-1.76-4.24l-1.41 1.41C15.55 9.9 16 10.9 16 12a4 4 0 0 1-4 4a4 4 0 0 1-4-4c0-1.86 1.28-3.41 3-3.86v2.14c-.6.35-1 .98-1 1.72a2 2 0 0 0 2 2a2 2 0 0 0 2-2c0-.74-.4-1.38-1-1.72V2h-1A10 10 0 0 0 2 12a10 10 0 0 0 10 10a10 10 0 0 0 10-10c0-2.76-1.12-5.26-2.93-7.07"/></svg>
diff --git a/.github/readme/icon-template.svg b/.github/readme/icon-template.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="#f59e0b" d="M6 2a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8l-6-6zm0 2h7v5h5v11H6zm2 8v2h8v-2zm0 4v2h5v-2z"/></svg>
diff --git a/.github/readme/icon-token.svg b/.github/readme/icon-token.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="#f59e0b" d="M11 15H6l7-14v8h5l-7 14z"/></svg>
diff --git a/.github/readme/icon-watch.svg b/.github/readme/icon-watch.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="#06b6d4" d="M12 10c-1.1 0-2 .9-2 2s.9 2 2 2s2-.9 2-2s-.9-2-2-2m6 2c0-3.3-2.7-6-6-6s-6 2.7-6 6c0 2.2 1.2 4.1 3 5.2l1-1.7c-1.2-.7-2-2-2-3.4c0-2.2 1.8-4 4-4s4 1.8 4 4c0 1.5-.8 2.8-2 3.4l1 1.7c1.8-1 3-3 3-5.2M12 2C6.5 2 2 6.5 2 12c0 3.7 2 6.9 5 8.6l1-1.7c-2.4-1.4-4-4-4-6.9c0-4.4 3.6-8 8-8s8 3.6 8 8c0 3-1.6 5.5-4 6.9l1 1.7c3-1.7 5-4.9 5-8.6c0-5.5-4.5-10-10-10"/></svg>
diff --git a/.github/readme/icon-workflow.svg b/.github/readme/icon-workflow.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="#06b6d4" d="M18 11h-3.18C14.4 9.84 13.3 9 12 9s-2.4.84-2.82 2H6c-.33 0-2-.1-2-2V8c0-1.83 1.54-2 2-2h10.18C16.6 7.16 17.7 8 19 8a3 3 0 0 0 3-3a3 3 0 0 0-3-3c-1.3 0-2.4.84-2.82 2H6C4.39 4 2 5.06 2 8v1c0 2.94 2.39 4 4 4h3.18c.42 1.16 1.52 2 2.82 2s2.4-.84 2.82-2H18c.33 0 2 .1 2 2v1c0 1.83-1.54 2-2 2H7.82C7.4 16.84 6.3 16 5 16a3 3 0 0 0-3 3a3 3 0 0 0 3 3c1.3 0 2.4-.84 2.82-2H18c1.61 0 4-1.07 4-4v-1c0-2.93-2.39-4-4-4m1-7a1 1 0 0 1 1 1a1 1 0 0 1-1 1a1 1 0 0 1-1-1a1 1 0 0 1 1-1M5 20a1 1 0 0 1-1-1a1 1 0 0 1 1-1a1 1 0 0 1 1 1a1 1 0 0 1-1 1"/></svg>
diff --git a/.gitignore b/.gitignore
@@ -37,3 +37,4 @@ jira-cli-workspace/
 
 # Superpowers
 .superpower/
+.readme-craft/
diff --git a/README.md b/README.md

Original file line number	Diff line number	Diff line change
`@@ -37,3 +37,4 @@ jira-cli-workspace/`
`37`	`37`
`38`	`38`	`# Superpowers`
`39`	`39`	`.superpower/`
	`40`	`+.readme-craft/`