Tactile backgrounds · Agents

A tactile background is a standalone SVG that the Generation API (POST /api/generate) returns for a request with kind: "background". It needs no browser and no WebGL, and the same request always returns the same file. Use it when a live shader is not required, for example as a fixed web page background or as an image layer in Design Lab, Glyphfield's layered composition tool.

Tactile backgrounds have no Studio tool of their own. The HTTP API is the only way to generate them. Studio links that name the retired tool IDs backgrounds, logo or surface (for example /studio?tool=backgrounds) open Design Lab.

Settings

Every setting is optional. GET /api/generate returns the current contract. With a built-in preset or a complete identity, the default colors come from the identity's palette, and the default logo tone and color are the ones that read best on colorA. With preset: "custom", the default colors are #FFFFFF, #181818 and #737373 with a white logo.

Setting	Values	Default
`width`, `height`	64–4096 px each, at most 12,000,000 pixels in total	1200, 750
`style`	`gradient`, `grain-gradient`, `dither`, `pattern`	`gradient`
`gradient`	`linear`, `radial`, `mesh`, `orbit`, `wave`, `bloom`	`linear`
`colorA`, `colorB`, `colorC`	Six-digit HEX	From the identity
`angle`	−360 to 360	32
`focalX`, `focalY`	0–100	42, 38
`grain`	0–100. Applies to `grain-gradient`.	10
`relief`	0–80	18
`bandCount`, `bandDepth`, `bandGap`	3–24, 0–100, 0–64. Apply to the `mesh` gradient, which draws vertical bands.	15, 56, 0
`lightingEnabled`	`true` shades each band with a gradient. `false` fills each band with a flat color.	`true`
`ditherMatrix`, `ditherShape`	Bayer matrix 2, 4 or 8; `dots` or `squares`. Apply to `dither`.	4, `dots`
`pattern`, `patternOpacity`, `spacing`	`none`, `dots`, `lines`, `grid`, `fibers`, `speckles`, `topographic`, `crosshatch`; 0–100; 8–256 px	`none`, 12, 24
`surfaceMaterial`	`none`, `kerf-wood`, `woven-wire`, `perforated-metal`, `carved-stone`, `embossed-paper`, `brushed-metal`, `hammered-foil`, `corrugated-polymer`, `cork-composite`, `frosted-glass`, `iridescent-film`, `holo-cloth`, `linen-weave`, `felted-wool`, `pebbled-leather`, `crackle-glaze`, `sandblasted-plaster`, `graphite`, `carbon-twill`	`none`
`surfaceScale`, `surfaceAngle`	12–140, 0–180	44, 28
`surfaceDepth`, `surfaceRoughness`, `surfaceMetallic`, `surfaceIrregularity`, `surfaceTextureAmount`	0–100	28, 58, 0, 34, 72
`surfaceOpenArea`	0–92	52
`surfaceLibraryAssetId`	Empty, or one of the CC0 references below	Empty
`logoTone`, `logoColor`	`black` or `white`; six-digit HEX	From the identity
`logoScale`, `logoOpacity`, `logoX`, `logoY`	5–90, 0–100, −50 to 50, −50 to 50	28, 100, 0, 0

With style: "pattern", a pattern of none renders dots. The SVG embeds the identity's mark (mark-light for a white tone and mark-dark for a black tone) or the identity.logoDataUrl image. An identity without a mark gets its short name as text.

CC0 surface references

surfaceLibraryAssetId names one of eleven CC0 1.0 texture references from Poly Haven and ambientCG: polyhaven-velour-velvet, ambientcg-fabric-061, ambientcg-leather-037, polyhaven-oak-veneer, polyhaven-plywood, polyhaven-marble, polyhaven-metal-plate, ambientcg-metal-063, polyhaven-beige-wall, polyhaven-rubber-tiles and ambientcg-paper-006. The generated SVG records the ID in its data-surface-library-asset attribute and draws the texture from surfaceMaterial. GET /api/catalog publishes a preset for each reference under surfaceLibrary, with the surfaceMaterial settings that approximate it, its source and its attribution.

GET /api/surface-textures/<assetId>/<map> serves the available color, displacement, metalness, normal and roughness maps of these references from their providers, with X-Surface-License and X-Surface-Provider headers. It serves only these assets and maps and is not a general proxy.

Example

curl -fsS -X POST http://localhost:3012/api/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "background",
    "identity": { "preset": "gt" },
    "settings": {
      "width": 1600,
      "height": 900,
      "style": "grain-gradient",
      "gradient": "mesh",
      "surfaceMaterial": "embossed-paper",
      "surfaceDepth": 36,
      "surfaceRoughness": 72,
      "colorA": "#F4F4F4",
      "colorB": "#070707",
      "colorC": "#2F5CE0"
    },
    "output": "raw"
  }' -o tactile-background.svg

With output: "raw" the response is image/svg+xml. With output: "json" (the default) the SVG is in artifact.content, and the file is named <brand>-background-<width>x<height>.svg.

Use a background in the Studio

Upload the SVG to Design Lab with Add image layer. You can also add it to the Asset library in Brand identity as a background asset, so the Studio tools offer it from the identity's library. A material from the Shader Library is the animated alternative. The palette that supplies the default colors is edited in Color tokens and Brand identity.

Limits

64–4096 px per side and 12,000,000 pixels in total. Larger requests return invalid_dimensions or pixel_limit.
Request bodies up to 5,250,000 bytes. The request takes images only as base64 data URLs and does not fetch remote URLs.
The same request returns the same SVG.

See Generation API for the request envelope and errors.

Settings

CC0 surface references

Example

Use a background in the Studio

Limits

On this page