Gradient Pattern Generator / Kuro

English Documentation

Overview

Gradient Pattern Generator, internally named Kuro, is a browser-based generative design-system playground for creating reusable deep gradients, wave textures, optical masks, and procedural background recipes.

The project is not a static image gallery. It is a deterministic TypeScript engine plus a Vite/React playground. A visual result is stored as a preset: a seed, palette, size, layers, blend modes, and generator parameters. That preset can be previewed on Canvas, exported as CSS where possible, and exported as a TypeScript object for reuse in other projects.

The current focus is poster, brand image, thumbnail, and hero-background exploration. The long-term direction is a procedural visual design system: not only color tokens, but reusable gradient and pattern recipes.

What This Repository Does

Generates deterministic deep-gradient fields from seeds and palettes.
Lets users edit gradient points directly with visible handles.
Supports per-point range, blur, strength, falloff, ramp, and enabled state.
Adds wave-interference layers that can behave as overlays or masks.
Supports wave roles: overlay, alphaMask, inkMask, and lumaMask.
Supports wave scopes: local and global.
Provides wave styles and variants: contour, fiber, ripple, and flow.
Renders high-fidelity previews through Canvas.
Exports CSS background approximations.
Exports reusable TypeScript preset modules.
Keeps behavior reproducible through seeded random utilities.

Current Status

This is an early working MVP. It already includes the generative engine, validation, renderer, export helpers, tests, and a usable playground.

Implemented:

Vite + React + TypeScript app.
Preset schema and validation with Zod.
Seeded random utilities.
deepGradientField generator.
Manual gradient point controls.
Canvas point-handle editing for gradient points.
waveInterference generator.
Wave role/scope/style/variant controls.
Canvas renderer.
CSS export.
TypeScript preset export.
Vitest coverage for engine, renderer, validation, and export behavior.

Not implemented yet:

PNG/JPG export.
A dedicated saved-preset library.
Metaball rendering.
Noise flow fields.
Contour-line generator as a separate layer type.
Cloud sync, accounts, or collaboration.

Quick Start

Install dependencies:

npm install

Start the local playground:

npm run dev

Vite starts on http://127.0.0.1:5173/ by default. If that port is already in use, Vite may automatically choose the next available port.

Run type checking:

npm run typecheck

Run tests:

npm test -- --run

Build the production bundle:

npm run build

Project Structure

src/
  App.tsx                         Playground UI
  main.tsx                        React entry point
  styles.css                      Playground styling

  engine/
    types.ts                      Preset, layer, gradient, and wave types
    validation.ts                 Zod validation for presets and layer params
    random.ts                     Deterministic seeded random utilities
    color.ts                      Color parsing helpers
    resolvePreset.ts              Preset resolution entry point
    generators/
      deepGradientField.ts        Deep gradient and manual point generator
      waveInterference.ts         Wave field generator
      waveParameters.ts           Wave parameter normalization

  renderer/
    canvas.ts                     Canvas renderer

  export/
    css.ts                        CSS background export
    typescript.ts                 TypeScript preset export

  presets/
    deepOrganic01.ts              Example preset

docs/superpowers/
  specs/                          Product and feature design specs
  plans/                          Implementation plans

Core Concepts

Preset

A preset is the source of truth for a generated visual. It contains:

id
name
seed
size
palette
layers

Example:

const preset = {
  id: "deep-organic-01",
  name: "Deep Organic 01",
  seed: "kuro-001",
  size: { width: 1440, height: 900 },
  palette: {
    base: "#080A0F",
    stops: ["#1B4DFF", "#00D6A3", "#F4E06D", "#F26D5B"],
  },
  layers: [
    {
      type: "deepGradientField",
      blend: "screen",
      opacity: 0.9,
      params: {
        pointMode: "manual",
        fieldMode: "radial",
        points: [],
      },
    },
  ],
};

Deep Gradient Field

deepGradientField creates layered radial gradient fields. It supports two modes:

seeded: points are generated from the preset seed.
manual: points are stored explicitly in params.points.

Manual points support:

id
enabled
colorIndex
color
x
y
range
strength
blur
falloff
ramp

Supported falloff values:

linear
smooth
gaussian
hard
inverse

Supported ramp values:

soft-core
hard-edge
mist
spotlight
halo

Wave Interference

waveInterference creates optical texture and mask behavior.

Roles:

overlay: draws wave information as surface texture.
alphaMask: cuts into the rendered image.
inkMask: darkens the image like black ink or print pressure.
lumaMask: modulates perceived brightness through a soft-light style approximation.

Scopes:

local: applies where the layer appears in the stack.
global: queues the wave operator and applies it after the main composition.

Styles and variants:

contour: topographic, cutline
fiber: paper, thread
ripple: sonar, interference
flow: magnetic, smoke

Playground Workflow

Adjust the seed, preview ratio, and palette.
Edit gradient points with visible point handles.
Select a point and tune its range, blur, strength, falloff, and ramp.
Change wave role, scope, style, variant, density, softness, strength, and flow.
Inspect the Canvas preview.
Copy the CSS export when a CSS approximation is enough.
Copy the TypeScript preset when you want a reusable procedural recipe.

Rendering And Export Strategy

Canvas is the visual source of truth. CSS export is a practical approximation.

This matters because some effects are easy to describe in Canvas but hard to reproduce exactly in CSS:

global wave masks;
alpha/luma masking;
future metaball fields;
dense procedural texture.

The CSS exporter still produces useful radial gradients, repeating gradients, custom properties, and notes that explain when the Canvas renderer is more accurate.

Testing

The test suite covers:

color helpers;
deterministic random utilities;
preset validation;
deep gradient resolution;
manual gradient point behavior;
wave parameter normalization;
wave style variants;
Canvas renderer behavior;
CSS export behavior;
TypeScript export behavior.

Run all tests:

npm test -- --run

Important Design Documents

docs/superpowers/specs/2026-05-27-generative-design-system-design.md
docs/superpowers/specs/2026-05-27-wave-parameter-system-design.md
docs/superpowers/specs/2026-05-27-gradient-point-control-design.md
docs/superpowers/plans/2026-05-27-generative-engine-mvp.md
docs/superpowers/plans/2026-05-27-wave-parameter-system.md
docs/superpowers/plans/2026-05-27-gradient-point-controls.md

Roadmap

Near-term:

Improve point editing UX.
Add point creation, duplication, and removal controls.
Add PNG/JPG export.
Add preset save/load behavior.
Add more example presets.

Mid-term:

Add metaball rendering as a separate fieldMode.
Add noise flow fields.
Add contour-line layers.
Add visual preset browser.
Add export profiles for hero, poster, thumbnail, and wide layouts.

Long-term:

Promote strong presets into procedural design tokens.
Build a larger design-system vocabulary around generated backgrounds, masks, and textures.
Support richer brand-system boards and static graphic exports.

Development Notes

The package is currently marked "private": true. It is designed as a local playground and source repository, not a published npm package yet.

The engine is intentionally separate from the React UI. The playground should remain a client of the engine, not the owner of pattern logic.

License

No license file is currently included. Add a license before treating this as an open-source package.

한국어 문서

개요

Gradient Pattern Generator, 내부 이름 Kuro는 딥 그라디언트, 웨이브 텍스처, 광학적 마스크, 절차적 배경 레시피를 만들기 위한 브라우저 기반 생성형 디자인 시스템 플레이그라운드입니다.

이 저장소는 정적 이미지 모음이 아닙니다. 핵심은 결정론적 TypeScript 엔진과 Vite/React 플레이그라운드입니다. 하나의 결과물은 seed, palette, size, layer, blend mode, generator parameter를 가진 preset으로 저장됩니다. 이 preset은 Canvas에서 미리 볼 수 있고, 가능한 범위에서는 CSS로 export할 수 있으며, 다른 프로젝트에서 재사용할 수 있는 TypeScript 객체로도 export할 수 있습니다.

현재 초점은 포스터, 브랜드 이미지, 썸네일, hero background를 빠르게 탐색하는 것입니다. 장기 방향은 단순한 color token이 아니라, 재사용 가능한 gradient/pattern recipe까지 포함하는 절차적 비주얼 디자인 시스템입니다.

이 저장소가 하는 일

seed와 palette를 기반으로 결정론적인 deep gradient field를 생성합니다.
gradient point를 화면에서 직접 보고 편집할 수 있습니다.
point마다 range, blur, strength, falloff, ramp, enabled 상태를 조절할 수 있습니다.
wave interference layer를 overlay 또는 mask처럼 사용할 수 있습니다.
wave role을 지원합니다: overlay, alphaMask, inkMask, lumaMask.
wave scope를 지원합니다: local, global.
wave style과 variant를 지원합니다: contour, fiber, ripple, flow.
Canvas를 통해 고품질 preview를 렌더링합니다.
CSS background approximation을 export합니다.
재사용 가능한 TypeScript preset module을 export합니다.
seeded random utility를 통해 결과를 재현 가능하게 유지합니다.

현재 상태

이 프로젝트는 초기 MVP이지만 실제로 동작하는 상태입니다. 생성 엔진, validation, renderer, export helper, test, playground가 포함되어 있습니다.

구현된 것:

Vite + React + TypeScript app.
Zod 기반 preset schema와 validation.
seeded random utility.
deepGradientField generator.
manual gradient point control.
gradient point를 위한 Canvas handle editing.
waveInterference generator.
wave role/scope/style/variant control.
Canvas renderer.
CSS export.
TypeScript preset export.
engine, renderer, validation, export 동작을 검증하는 Vitest 테스트.

아직 구현되지 않은 것:

PNG/JPG export.
저장된 preset library.
metaball rendering.
noise flow field.
별도 layer type으로서의 contour-line generator.
cloud sync, account, collaboration.

빠른 시작

의존성을 설치합니다:

npm install

로컬 playground를 실행합니다:

npm run dev

기본 Vite 주소는 http://127.0.0.1:5173/입니다. 해당 port가 이미 사용 중이면 Vite가 자동으로 다음 사용 가능한 port를 선택할 수 있습니다.

타입 체크를 실행합니다:

npm run typecheck

테스트를 실행합니다:

npm test -- --run

프로덕션 빌드를 실행합니다:

npm run build

프로젝트 구조

src/
  App.tsx                         Playground UI
  main.tsx                        React entry point
  styles.css                      Playground styling

  engine/
    types.ts                      Preset, layer, gradient, wave type
    validation.ts                 Preset과 layer params를 검증하는 Zod schema
    random.ts                     결정론적 seeded random utility
    color.ts                      Color parsing helper
    resolvePreset.ts              Preset resolution entry point
    generators/
      deepGradientField.ts        Deep gradient와 manual point generator
      waveInterference.ts         Wave field generator
      waveParameters.ts           Wave parameter normalization

  renderer/
    canvas.ts                     Canvas renderer

  export/
    css.ts                        CSS background export
    typescript.ts                 TypeScript preset export

  presets/
    deepOrganic01.ts              Example preset

docs/superpowers/
  specs/                          Product/feature design spec
  plans/                          Implementation plan

핵심 개념

Preset

Preset은 생성된 비주얼의 source of truth입니다. 다음 값을 포함합니다:

id
name
seed
size
palette
layers

예시:

const preset = {
  id: "deep-organic-01",
  name: "Deep Organic 01",
  seed: "kuro-001",
  size: { width: 1440, height: 900 },
  palette: {
    base: "#080A0F",
    stops: ["#1B4DFF", "#00D6A3", "#F4E06D", "#F26D5B"],
  },
  layers: [
    {
      type: "deepGradientField",
      blend: "screen",
      opacity: 0.9,
      params: {
        pointMode: "manual",
        fieldMode: "radial",
        points: [],
      },
    },
  ],
};

Deep Gradient Field

deepGradientField는 여러 radial gradient field를 쌓아 깊이 있는 배경을 만듭니다. 두 가지 mode를 지원합니다:

seeded: preset seed를 기반으로 point를 생성합니다.
manual: params.points에 저장된 point 배열을 그대로 사용합니다.

Manual point가 지원하는 값:

id
enabled
colorIndex
color
x
y
range
strength
blur
falloff
ramp

지원되는 falloff 값:

linear
smooth
gaussian
hard
inverse

지원되는 ramp 값:

soft-core
hard-edge
mist
spotlight
halo

Wave Interference

waveInterference는 optical texture와 mask 동작을 만듭니다.

Role:

overlay: wave 정보를 표면 texture로 얹습니다.
alphaMask: 렌더링된 이미지를 잘라냅니다.
inkMask: 검정 잉크나 인쇄 압력처럼 이미지를 어둡게 누릅니다.
lumaMask: soft-light 계열 approximation으로 밝기감을 변조합니다.

Scope:

local: layer stack에서 해당 위치에 적용됩니다.
global: main composition 이후에 전체 결과에 적용됩니다.

Style과 variant:

contour: topographic, cutline
fiber: paper, thread
ripple: sonar, interference
flow: magnetic, smoke

Playground 사용 흐름

seed, preview ratio, palette를 조절합니다.
보이는 point handle로 gradient point를 편집합니다.
point를 선택하고 range, blur, strength, falloff, ramp를 조절합니다.
wave role, scope, style, variant, density, softness, strength, flow를 바꿉니다.
Canvas preview를 확인합니다.
CSS approximation이 충분하면 CSS export를 복사합니다.
절차적 recipe로 재사용하고 싶으면 TypeScript preset export를 복사합니다.

Rendering And Export Strategy

Canvas가 시각적 source of truth입니다. CSS export는 실용적인 approximation입니다.

이 구분이 중요한 이유는 일부 효과가 Canvas에서는 자연스럽지만 CSS에서는 정확히 재현하기 어렵기 때문입니다:

global wave mask;
alpha/luma masking;
future metaball field;
dense procedural texture.

그래도 CSS exporter는 radial gradient, repeating gradient, custom property, 그리고 Canvas renderer가 더 정확한 경우를 설명하는 note를 제공합니다.

Testing

테스트 범위:

color helper;
deterministic random utility;
preset validation;
deep gradient resolution;
manual gradient point behavior;
wave parameter normalization;
wave style variant;
Canvas renderer behavior;
CSS export behavior;
TypeScript export behavior.

전체 테스트 실행:

npm test -- --run

주요 설계 문서

docs/superpowers/specs/2026-05-27-generative-design-system-design.md
docs/superpowers/specs/2026-05-27-wave-parameter-system-design.md
docs/superpowers/specs/2026-05-27-gradient-point-control-design.md
docs/superpowers/plans/2026-05-27-generative-engine-mvp.md
docs/superpowers/plans/2026-05-27-wave-parameter-system.md
docs/superpowers/plans/2026-05-27-gradient-point-controls.md

Roadmap

단기:

point editing UX 개선.
point 생성, 복제, 삭제 control 추가.
PNG/JPG export 추가.
preset save/load 동작 추가.
더 많은 example preset 추가.

중기:

metaball rendering을 별도 fieldMode로 추가.
noise flow field 추가.
contour-line layer 추가.
visual preset browser 추가.
hero, poster, thumbnail, wide layout export profile 추가.

장기:

강한 preset을 procedural design token으로 승격.
생성형 background, mask, texture를 중심으로 더 큰 design-system vocabulary 구축.
brand-system board와 static graphic export 지원.

개발 노트

현재 package는 "private": true로 설정되어 있습니다. 아직 npm package로 배포하기보다는 로컬 playground와 source repository로 사용하는 구조입니다.

엔진은 React UI와 분리되어 있습니다. Playground는 engine의 client여야 하며, pattern logic의 owner가 되지 않아야 합니다.

License

현재 license file은 포함되어 있지 않습니다. 공개 open-source package처럼 사용하려면 license를 먼저 추가해야 합니다.

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
docs/superpowers		docs/superpowers
src		src
.gitignore		.gitignore
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

Gradient Pattern Generator / Kuro

English Documentation

Overview

What This Repository Does

Current Status

Quick Start

Project Structure

Core Concepts

Preset

Deep Gradient Field

Wave Interference

Playground Workflow

Rendering And Export Strategy

Testing

Important Design Documents

Roadmap

Development Notes

License

한국어 문서

개요

이 저장소가 하는 일

현재 상태

빠른 시작

프로젝트 구조

핵심 개념

Preset

Deep Gradient Field

Wave Interference

Playground 사용 흐름

Rendering And Export Strategy

Testing

주요 설계 문서

Roadmap

개발 노트

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages