Shape

The shape language of Axiom: a rectangle with four corners and one feature per side, described as numbers and resolved into lines and arcs.

A shape is a rectangle with decorations. Its four corners can be round, beveled, scooped, notched, and they can move into the box; each side can carry one feature, a bump or a notch. You describe all of that as numbers, and resolve turns the description into an outline of straight lines and circular arcs.

This is the geometry under every surface. @ax-design/surface reads the same values from its --ax-* custom properties and calls the library for you, so most of the time you write only CSS; the examples here use the library directly, so you can see what each value does to the outline, and the last one animates a surface with the same values written as CSS. The Playground has every property with live controls.

Shape has no DOM dependency. The same outline becomes an SVG path, traces on a canvas, or computes a border ring and a tilt on the server.

npm install @ax-design/shape

import { resolve, toSvgPath, traceContour, borderInner, tiltHomography } from '@ax-design/shape';

You hand resolve a box, four corners and four sides. It answers with an outline: a closed path of line and arc segments. The dotted frame in the preview is the sharp contour before any rounding, with a dot at every vertex; the white shape is what the outline draws.

Nothing is measured from the page, so the same call runs anywhere: toSvgPath writes the contour as an SVG path, traceContour traces it on a canvas context or a Path2D.

import { resolve, toSvgPath, traceContour } from '@ax-design/shape';

const corner = { radius: 30, shape: 'scoop', shiftX: 0, shiftY: 0 };
const flat = { kind: 'flat', depth: 0, span: 0, at: 0.5, ratio: 0.5, tipRadius: 0, shoulderRadius: 0 };

const shape = resolve({
  width: 200,
  height: 140,
  corners: [corner, corner, corner, corner],
  edges: [flat, flat, flat, flat],
});

toSvgPath(shape.outline);          // SVG
traceContour(ctx, shape.outline);  // Canvas

.shape {
  --ax-radius: 30px;
  --ax-corner-shape: scoop;
}

The radius is a fillet: a circle that touches both sides, so the corner leaves them smoothly. The library takes px; Surface also accepts percentages, measured against the shorter side. Like border-radius, radii that do not fit are scaled down rather than overflowing.

The corner shape draws a different curve between those two same tangent points. round is the fillet, bevel cuts straight across, scoop bends the other way and notch cuts in with sharp points. Because the tangent points stay put, changing the shape never changes where the corner meets the sides.

const flat = { kind: 'flat', depth: 0, span: 0, at: 0.5, ratio: 0.5, tipRadius: 0, shoulderRadius: 0 };
const corner = { radius: 34, shape: 'round', shiftX: 0, shiftY: 0 };

resolve({ width: 200, height: 140, corners: [corner, corner, corner, corner], edges: [flat, flat, flat, flat] });

.shape {
  --ax-radius: 34px;
  --ax-corner-shape: round;
}

A bevel, scoop or notch meets the side in a point, so the corner enters the side at an angle. The shoulder radius rounds that meeting: the corner leaves the side smoothly, as a fillet would. A round corner is already smooth and ignores it.

Turn the radius up to half the side and the scoop corners of a square meet in the middle of every edge. Rounding those four points turns the square into a soft star; a large enough shoulder closes the star into a circle.

const flat = { kind: 'flat', depth: 0, span: 0, at: 0.5, ratio: 0.5, tipRadius: 0, shoulderRadius: 0 };
const corner = { radius: 90, shape: 'scoop', shiftX: 0, shiftY: 0, shoulderRadius: 12 };

resolve({ width: 180, height: 180, corners: [corner, corner, corner, corner], edges: [flat, flat, flat, flat] });

.shape {
  --ax-radius: 90px;
  --ax-corner-shape: scoop;
  --ax-corner-shoulder-radius: 12px;
}

shiftX and shiftY move a corner point: positive values point into the shape, negative values out of it. Every corner moves on its own, and the two sides that meet there follow it.

Move the top left and the bottom right corner the same way and the rectangle slants into a parallelogram. Move all four toward the middle for a diamond, or only the two top corners for a trapezoid. Two corners that land on the same point merge into one.

const flat = { kind: 'flat', depth: 0, span: 0, at: 0.5, ratio: 0.5, tipRadius: 0, shoulderRadius: 0 };
const corner = (shiftX, shiftY) => ({ radius: 12, shape: 'round', shiftX, shiftY });

resolve({
  width: 200,
  height: 140,
  corners: [
    corner(36, 0),  // top left
    corner(0, 0),           // top right
    corner(36, 0),       // bottom right
    corner(0, 0),           // bottom left
  ],
  edges: [flat, flat, flat, flat],
});

.shape {
  --ax-corner-top-left-shift-x: 36px;
  --ax-corner-top-left-shift-y: 0px;
  --ax-corner-bottom-right-shift-x: 36px;
}

Each side can carry one feature. kind picks what it is: arc is a circular bump or notch, rect, triangle and trapezoid are straight, and cusp is the two-arc one on the next column. depth says how far it goes, positive out of the shape and negative into it. span is the width of its base in px, and at places its middle along the side, from 0 to 1.

Sides run clockwise: top, right, bottom, left. Put the same feature on every side and the same at turns each one the same way around the box, so the result has rotational symmetry rather than mirror symmetry.

const flat = { kind: 'flat', depth: 0, span: 0, at: 0.5, ratio: 0.5, tipRadius: 0, shoulderRadius: 0 };
const feature = { kind: 'arc', depth: -24, span: 90, at: 0.5, ratio: 0.5, tipRadius: 0, shoulderRadius: 0 };

resolve({
  width: 200,
  height: 140,
  corners: [corner, corner, corner, corner],
  // top, right, bottom, left
  edges: [feature, flat, flat, flat],
});

.shape {
  --ax-edge-top-kind: arc;
  --ax-edge-top-depth: -24px;
  --ax-edge-top-span: 90px;
  --ax-edge-top-at: calc(0.5 * 100%);
}

A cusp is two arcs, each leaving the side smoothly at one end of the span, meeting in a point. It is the one kind that needs no shoulder radius: the arcs already leave the side tangentially.

Pointing into the shape it pinches the side, like the waist of the bun or the gaps between the leaves of a clover. Pointing out it makes a pointed arch. The tip radius rounds the meeting point, and at zero the point stays sharp.

const flat = { kind: 'flat', depth: 0, span: 0, at: 0.5, ratio: 0.5, tipRadius: 0, shoulderRadius: 0 };
const cusp = { kind: 'cusp', depth: -22, span: 180, at: 0.5, ratio: 0.5, tipRadius: 10, shoulderRadius: 0 };

resolve({
  width: 180,
  height: 160,
  corners: [corner, corner, corner, corner],
  edges: [flat, cusp, flat, cusp],  // top, right, bottom, left
});

.shape {
  --ax-edge-right-kind: cusp;
  --ax-edge-right-depth: -22px;
  --ax-edge-right-span: 180px;
  --ax-edge-right-tip-radius: 10px;
}

A radius larger than the side, a feature wider than the space left between two corners: none of it overflows or throws. Values are scaled down until they fit, the same way CSS does with border-radius, and a corner and the feature next to it share the straight part of the side and shrink together.

shape.clamps lists every value that was scaled and by how much, so a tool can tell the reader what it had to do. Push the radius and the span until the readout fills up.

const feature = { kind: 'arc', depth: -20, span: 90, at: 0.5, ratio: 0.5, tipRadius: 0, shoulderRadius: 0 };

const shape = resolve({
  width: 200,
  height: 70,
  corners: [corner, corner, corner, corner],
  edges: [feature, flat, flat, flat],
});

shape.clamps; // [{ kind: 'corner-radius', index: 1, factor: 0.62 }, ...]

.shape {
  --ax-radius: 24px;
  --ax-edge-top-span: 90px;
}

A border is a ring: the outline, and an inner edge at the same distance inside. borderInner offsets every segment by its own width, joins neighbours where the offset lines cross, and drops segments that turned around in a narrow place, so a ring works on a shape of any complexity. Fill the two contours with the even-odd rule and the ring is what stays between them.

The widths are per side, so one side can be thicker than the others. Pass the tilt of the element and the width is kept as it appears on screen (next column).

import { borderInner, traceInner } from '@ax-design/shape';

const { inner } = borderInner(shape.outline, { widths: [6, 6, 6, 6] });

ctx.beginPath();
traceContour(ctx, shape.outline);
traceInner(ctx, inner);
ctx.fill('evenodd');

.shape {
  --ax-border-width: 6px;
  --ax-radius: 30px;
}

When the element is tilted with perspective() and rotateX() / rotateY(), a border taken from the untilted outline would thin on the far side. Pass the tilt as a homography and borderInner offsets in screen space instead: the inner edge comes back in local coordinates, so the ring keeps the same thickness everywhere on screen.

Both shapes below share one outline and one homography. The left one ignored the tilt, the right one passed it. The readout is the thickness borderInner reports for the right one.

import { borderInner, tiltHomography } from '@ax-design/shape';

const transform = tiltHomography({
  width: 140,
  height: 100,
  perspective: 400,
  rotateX: 18,
  rotateY: 30,
  translateZ: 0,
});

const { inner, thickness } = borderInner(shape.outline, { widths: [8, 8, 8, 8], transform });
// thickness: the same on every side, as seen on screen

A shape is numbers, so a shape can move. Give the properties a transition or an animation and the outline follows: Surface registers every shape property with CSS.registerProperty, so the browser interpolates the numbers. Without registration, an animation of a custom property is applied in steps, and the shape would jump from one value to the next.

The keyframes below move the radius, the four shifts and the shared edge depth together, so a circle becomes a square, then a diamond, then a star and back. A frame whose values do not fit is scaled down on the way, exactly like a shape at rest, so an animation cannot break the outline.

Each frame resolves the shape again. The same call runs whether the numbers came from a stylesheet, from a spring or from your own code.

<ax-surface class="morph" layers="fill"></ax-surface>

.morph {
  animation: shape-morph 8s cubic-bezier(0.6, 0, 0.3, 1) infinite;
}

@keyframes shape-morph {
  0%, 100% { --ax-radius: 50%; --ax-edge-depth: 0px; }
  25%      { --ax-radius: 28%; --ax-edge-depth: 0px; }
  50%      { --ax-radius: 14%; --ax-corner-top-left-shift-y: 50%; --ax-corner-top-right-shift-x: 50%; --ax-corner-bottom-right-shift-y: 50%; --ax-corner-bottom-left-shift-x: 50%; --ax-edge-depth: 0px; }
  75%      { --ax-radius: 19%; --ax-edge-depth: 22px; }
}

import { borderWidthsFrom, shapeSpecFrom } from '@ax-design/surface';

// Surface runs this on every frame, from the values it just read: a shape in motion is a
// shape resolved again.
resolve(shapeSpecFrom(values, width, height), { borderWidths: borderWidthsFrom(values) });

Reference