Skip to content
flyingsalmon

Principles

Bold, warm, and social: a flat, light, orange system that tells you what happened where you are already looking.

flyingsalmon is an opinionated design system: an app built from it feels like making plans with friends, not like filing a form. Four principles decide everything else: feedback appears where the user is looking, surfaces are flat, every colour comes from the palette, and every space is a step on one scale. Each one is a choice the components make for you so an app built from them agrees without anyone coordinating.

Where a result belongs

The three homes, in order

Feedback appears where the user’s attention already is and stays until they have seen it. Use the first home that fits. The registry enforces this only on its own components: none has an auto-dismiss prop, the notice holds one item, and alerts and field errors announce themselves. Where an app puts its feedback is the app’s choice, so this ranking is guidance.

OrderHomeComponentUse it for
1The affected itemCard, table row, listSuccess is the item appearing or updating: a new trip at the top of the list needs no words. Failure is a failed state on the item with its message and a retry.
2The acting surfaceForm result slot, AlertThe result slot below the form’s actions row, for client-side validation across fields and for page forms whose server is the validator, such as sign in or payment.
3The noticeNoticeA shell-owned, persistent surface for a result with no visible home: after navigation, after a dialog form has closed, or for an action with nothing to show, such as a copied link.

What is banned, and why

Feedback that has any of these properties is banned, whatever it is called. A bottom-right toast has all four. A notice has none of them, so a notice is allowed and a toast is not.

MarkPropertyLooks likeWhy it fails
×Auto-dismissesA timerA result that leaves on a clock can leave before the reader looks. Feedback stays until it has been seen.
×StacksSeveral at onceA pile of results is a queue to be cleared, not a message. One result at a time, replaced by the next.
×Has no ownerFloating, unattachedA result nothing in the app is responsible for cannot be updated, dismissed, or retried by anyone.
×Has no link backNo subjectA message that cannot take you to the thing it is about leaves you guessing what it means.

Dialog forms

A dialog form closes on submit and leaves no result inside it. Success shows on the item that changed. A new trip in the list cannot be missed.

A server error becomes a notice whose link reopens the dialog with what the user typed. The dialog is gone, so the notice is the one home that stays until it is seen, and nothing typed is lost. The dialog closes on submit, so nobody waits on it. Validation the app can do on the client stays in the dialog, under the field.

A dropdown menu action follows the same order. Its result shows on the affected item, and only when no item is visible does a notice carry it. A notice about an item that is on screen is a bug, because the item’s own state is the right home.

Who shows what

The acting component shows its own busyness: a button morphs through a loading state and a field shows its own error. The app owns success and failure of the action as a whole. Position is never the objection to a result. The objection is that it is missed.

Flat surfaces

There are no shadows and no elevation tokens. Surfaces separate by solid border and background step, and interaction feedback lives in the border. Depth that comes from blur reads as generic. A hard edge reads as drawn, which suits the warm and hand-made mood.

Solid border
Background step
Border feedback

Palette only

Every colour is a step from the Tailwind OKLCH palette, behind a functional token such as --primary. There is no colour alpha, so a colour reads the same on every surface. Light mode only. The colour page lists every token.

Spacing

Every padding, gap, margin, and size is a step on Tailwind’s 4px scale. Card, dialog, and timeline expose their spacing as a variable instead of a density prop, so one override moves every inset in the surface together.

Usage rules

  • Do
    Show a successful save as the item appearing or updating.The changed item is where the user is already looking, and it needs no words to be understood.
  • Do
    Put a form’s result in the slot below its actions row.The button the user just pressed never moves, and the result sits beside it on short and long forms alike.
  • Don’t
    Show a notice about an item that is on screen.The item’s own state is a stronger signal, and a second message about the same thing competes with it.
  • Don’t
    Move content the user did not cause to move when a server result arrives.A field error growing under the field the user just left is movement they caused. A result arriving unprompted must not shove the page about.
  • Don’t
    Add a shadow to separate a surface.Use a solid border or a background step. Shadows blur the flat, drawn look the system is built on.
  • Don’t
    Reintroduce a toast under another name.A floating message that dismisses itself, stacks, or has no link to its subject fails the same way a toast does.

  • Notice

    The last home for a result.
  • Dialog

    The dialog form flow, from submit to notice.
  • Form

    The result slot below the actions row.