My Puppertino app

` for the card and a real heading for the title, so a screen reader announces the notification as a unit. Use `` for the timestamp with a machine-readable `datetime` attribute. "now" and "9:41 AM" are readable to people but not to anything else. The icon is decoration next to a title that already names the app, so give it an empty `alt`. ## The macOS notification `notifications.css` ships both. `.p-notification` alone is the macOS banner. Adding `.p-notification-touch` swaps it to iOS metrics: a larger icon, a bigger radius, and the time moved into the corner. --- # Mobile components: Empty states Source: https://puppertino.com/docs/mobile/empty-states/ What a screen shows when it has nothing to show. A glyph, a short message, a sentence, and one action that fixes it. An empty state is what a screen shows before it has any content. It explains why the screen is blank and offers the one action that changes that. ## When to use it Use an empty state anywhere a list, a search, or a whole screen can legitimately have nothing in it: an inbox before the first message, a folder before the first file, a search with no matches. An empty screen with nothing on it reads as a loading failure. An empty state turns the same screen into an explanation. Distinguish the three cases, because they need different words: | Case | Message | Action | |---|---|---| | Nothing yet | Explain what will appear here | The thing that creates the first one | | Nothing found | Say what was searched for | Clear the search or widen it | | Nothing to do | Say the work is done | Often none | ## Anatomy ```html

No Messages

Messages you receive will appear here.

Start a Conversation

``` | Part | Value | |---|---| | Glyph | 41px, in the accent | | Title | 22px, weight 590, line height 28px | | Message | 22px, weight 510, `rgba(60,60,67,0.60)` | | Message width | 30ch, so a centered sentence stays readable | | Badge | 50px circle, the glyph's tint at 15%, holding a 22px glyph | | Action | Full width to 330px, 52px tall, full capsule, no drop shadow, a glow rising into the bottom edge | | Padding | 32px vertical, 34px horizontal | The message is the same size as the title and one weight lighter, which is unusual. Most interfaces drop the supporting text a size or two. iOS keeps both at 22px and separates them with weight and color instead. The action is an ordinary touch button with `.p-empty-state__action` widening it and setting the 52px height. Compose it with any button style. The prominent glass button, `.p-button-glass-prominent`, is the usual choice, since an empty state has exactly one thing worth doing. A plain filled button works too, and gets the same glass lines along its edges. ## Variants ```html

No Results

No files match “budget”.

All Caught Up

You have read everything in this folder.

``` The glyph and the action are both optional. A "nothing found" state often has no action worth offering, and a "nothing to do" state often needs no glyph. `.p-empty-state-compact` drops the glyph to 22px and sets it in a 50px circle washed with its own tint at 15%, for an empty state inside a panel or a popover. The same badge is available on its own as `.p-empty-state__badge`: ```html ``` The glyph does not have to be blue. Set `--p-empty-glyph` on the empty state to any system color and the glyph and its badge follow: `style="--p-empty-glyph: var(--p-sys-pink)"`. `.p-empty-state-fill` gives the block `flex: 1` and a 240px minimum, so an empty state inside a list or a sheet centers in that region instead of sitting at the top of it. `.p-empty-state-anchored` pushes the action to the bottom of the available space, which is where iOS puts it on a full screen. ## Writing the content Title in title case, a few words, naming what is missing. "No Messages", not "Nothing here". Message as one complete sentence explaining what will appear or why nothing did. Say what was searched for when the state is a search result; "No files match "budget"" is useful in a way that "No results" is not. Avoid apologising, and avoid exclamation marks. The screen is empty because of where the person is, not because something went wrong. ## Dark mode The title moves to `rgba(255,255,255,0.92)`, the message to `rgba(235,235,245,0.60)`, and the glyph from `#0088FF` to `#0091FF`. ## Accessibility Use a real heading for the title so the empty state appears in the page outline, and keep the level consistent with the screen it replaces. The glyph is decoration next to a title that already says what is missing, so mark it `aria-hidden="true"`. When an empty state replaces a list that was previously populated, put it in a container with `aria-live="polite"` so a screen reader announces the change rather than leaving the person in a silent empty region. --- # Mobile components: Date pickers Source: https://puppertino.com/docs/mobile/date-pickers/ The iOS calendar. A glass panel with 38px day circles, 20px numbers, a neutral circle for the selected day, opened from a capsule value button. A date picker collects a date, a time, or both. On touch it is a month grid with cells big enough to hit, opened from a button showing the current value. ## When to use it Use a date picker when the answer is a real date and the surrounding dates matter: choosing a day to travel, booking a slot, setting a deadline. Use a plain text field with `type="date"` when you only need the value and the platform's own picker is good enough, which is often. A native picker is one line of markup and works everywhere. ## The value button iOS does not show a calendar inline. It shows the current value as a quiet capsule, and opens the calendar when that is tapped. ```html ``` That capsule is an ordinary touch button in the gray style, at the same 34px height and `rgba(118,118,128,0.12)` fill as everywhere else. There is no separate component for it. ## The calendar ```html

Time

``` | Part | Value | |---|---| | Panel | 370px wide, 13px radius, 12px side padding | | Material | Overlay glass: the fill, keyline, and rims of the alert surface, over `--p-shadow-overlay` (`0 8px 48px`, 25% light, 45% dark) | | Month title | 17px, weight 590, tracking -0.43px, with a 13px bold accent chevron | | Previous / next | 20pt chevrons in the label color, 44px targets | | Weekday header | 13px, weight 590, uppercase, at 30% | | Day circle | 38 x 38px | | Grid | 51px column pitch, 51px row pitch (48px for the first row) | | Day number | 20px, weight 400, tracking -0.45px | | Today | Accent number on a 12% accent circle | | Selected | Black circle, white 590 number (white circle, black number in dark) | | Time row | 52px, a hairline above, "Time" at 17px and a value capsule | The panel is glass because iOS presents the calendar as a popover over its value buttons, so it borrows the same overlay material as the alerts and menus. Add `.p-calendar-touch-plain` to drop the surface when the calendar sits inline on a card of its own. Reduced transparency and increased contrast swap the glass for an opaque panel. The circles are spread with `space-between` rather than dropped into seven equal columns, so the first and last circle in a row sit flush against the panel's padding. The 38px circle is smaller than a 44px target; the cells sit on a 51px grid, so a tap anywhere near a number still lands on it. Today and selected are two different marks. Today is the accent: a blue number on a faint blue circle. Selected is neutral: a black circle, or white in dark mode, so the choice reads the same whatever the app's tint is. A day can be both, and the selection wins. ### Tinted selection `.p-calendar-touch-tinted` fills the selected day with the accent instead, for a calendar that should carry the app's tint. ```html

``` ### The script The grid is driven by `datepickers.js`, the same script the pointer calendar uses. For a `.p-calendar-touch` it builds the month the iOS way: Sunday first, the full month name, SUN to SAT headers, no days from the neighbouring months, and only as many rows as the month needs. Set the selected day with `data-p-date="YYYY-MM-DD"`; it fires a bubbling `p-change` event with `{ date }` when a day is chosen. ```html ``` An optional `.p-calendar-time` row goes inside the calendar; the script keeps it below the grid. ## Dark mode Numbers flip from black to white, the accent from `#0088FF` to `#0091FF`, and the selected circle inverts: white with a black number. The panel's glass turns to `rgba(26,26,26,0.9)` and its shadow deepens to 45%. Weekday headers stay at 30% against the light values. ## Accessibility Day cells are buttons. The script names each one in full, "Monday, April 20, 2026", and marks the chosen day with `aria-pressed`; hand-written markup can use `aria-selected="true"`, which drives the same visual state. Weekday headers are `` elements with the full day name as the title, so "SUN" is not left to be guessed at. The month title is a polite live region, so moving between months is announced. Focus draws a 3px accent ring inset into the circle. A calendar is a lot of controls. Always offer a text alternative for the same value, so people who do not want to navigate 30 buttons can type a date instead. ## The macOS calendar `pickers.css` ships both. `.p-calendar` alone is the macOS graphical picker: 11px numbers on an 18px pitch with a 16px pill, sized for a pointer. Adding `.p-calendar-touch` swaps it to iOS metrics. Touch clears the macOS hover fill on day cells, since touch has no hover, and replaces the macOS gray today pill with the blue circle. --- # Desktop components: Buttons Source: https://puppertino.com/docs/desktop/buttons/ Push buttons for macOS interfaces. Six styles, four sizes, full state coverage, retinted by dropping any color class on the element. A push button starts an instantaneous action. People press it, something happens, the interface responds. Puppertino ships six push button styles in four sizes. Pick the style that matches the role of the action, the size that matches the density of the layout, and add a color class if you want to retint. ## When to use a button Use a button for direct actions. Save, Delete, Continue, Cancel. Anything where pressing the control causes a discrete change. Use a link for navigation. If pressing the control takes the person to a different page or section, that is a link. Avoid stacking more than one filled `.p-button-primary` in the same view. Apple's rule: one prominent action per screen. Multiple primary buttons compete for attention and weaken both. ## Anatomy | Token | Default value | Notes | |---|---|---| | `--p-button-height` | 24px | Regular size. Mini is 16px, small is 19px, large is 32px. | | `--p-button-padding-x` | 16px | Horizontal padding on each side. | | `--p-button-radius` | 6px | macOS regular button radius. Large jumps to 8px. | | `--p-button-font-size` | 13px | Matches macOS body. SF Pro fallback to system fonts. | | `--p-button-font-weight` | 510 | Apple's "system medium." Large bumps to 590 (semibold). | | `--p-button-icon-size` | 13px | Matches the label. SVG and `` children both scale to this token. | | `--p-button-default-tint` | `var(--p-control-accent)` | The control accent: `#0088FF` in light mode, `#0091FF` in dark. Used when no color class is set. | | `--p-button-fill` | `rgba(0,0,0,0.08)` | Gray fill for Default and Tinted. `rgba(255,255,255,0.07)` in dark mode. | | `--p-button-tint-mix` | 20% | How much accent the Secondary and Destructive washes carry. 22% in dark mode. | Override any token on a specific button with an inline style or a new class. The button picks up the change without you writing new selectors. ## Variants Combine `.p-button` with one style class to pick a role. ### Default ```html ``` For neutral actions in toolbars and dialogs. Light fill, primary text color, no claim on attention. ### Colored ```html ``` A filled accent button that picks up the current tint. Use it for the most important action in a group when that action is not the default-Return-key action. ### Secondary ```html ``` A tinted variant of Colored. Background sits at 20% of the tint, text uses the full tint. Use it for affirmative actions that should not steal focus from a primary. ### Destructive ```html ``` Always red, and it ignores any color class you drop on it. Use it only when the action removes data that cannot be recovered. Pair it with confirmation when the action is irreversible. ### Primary ```html ``` The default action. It shares Colored’s appearance and additionally responds to the Return key. ### Borderless ```html ``` Text only, in the accent, with no background in any state. Pressing darkens the label. Use it for tertiary actions that should feel like links inside a dense interface. Toolbar overflow menus, footer affordances, “Show more” toggles. ## Changing the color Add a color class to any button to change its tint. The button picks up the color, the hover and active states darken from it, and the focus ring matches. ```html ``` Reach for the `.p-sys-*` classes first. They follow the macOS system colors and flip automatically in dark mode. The brand palette (`.p-strawberry`, `.p-grape`, `.p-lime`) is available for backwards compatibility, but its colors stay fixed across appearances. A color class only retints the element you put it on. Dropping `.p-strawberry` on a card does not bleed into the buttons inside it. If you want a button to be strawberry, put the class on the button. ## Sizes Four sizes derived from macOS HIG. Mini and small target dense pointer interfaces (toolbars, sidebars, inspector panels). Regular is the default. Large is for prominent dialog actions. ```html ``` | Size | Class | Height | Padding | Font | Radius | |---|---|---|---|---|---| | Mini | `.p-button-mini` | 16px | 7px | 10px | 4px | | Small | `.p-button-small` | 19px | 9px | 11px | 5px | | Regular | (default) | 24px | 16px | 13px | 6px | | Large | `.p-button-large` | 32px | 16px | 13px semibold | 8px | Mini and small are pointer-only by design. They sit below the 44px touch-target guideline because macOS expects a mouse. For anything that needs to work on touch, use Regular or Large. ## Icons Drop an `` icon font tag inside the button. Put it before the label for a leading icon, after the label for a trailing icon. ```html ``` The icon picks up the button's text color and resizes with the button's size. You do not need a separate class for leading or trailing icons. The DOM order is the order. ## Icon-only buttons Add `.p-button-icon-only` for a round button that holds a single glyph. It is a true circle, as wide as it is tall, with a slightly heavier gray fill than a labeled button so the small shape still reads as pressable. ```html ``` | Size | Class | Diameter | Glyph | |---|---|---|---| | Mini | `.p-button-mini` | 16px | 11px | | Small | `.p-button-small` | 20px | 13px | | Regular | (default) | 24px | 13px | | Large | `.p-button-large` | 28px | 13px | | Extra large | `.p-button-xlarge` | 36px | 13px | Icon-only buttons follow the same size ladder as segmented controls and pop-up buttons, so small is 20px here and large is 28px. The fill sits at 10% black at rest, 19% pressed, and 5% disabled. In dark mode the same percentages apply in white. Always give an icon-only button an `aria-label`. Without one, screen readers have nothing to announce. ```html ``` ## States Every state derives from the button's current color, so a retinted button retints its states too. Each style presses in its own way. ```html ``` | State | Default and Tinted | Secondary and Destructive | Colored and Primary | |---|---|---|---| | Rest | 8% gray fill | 20% wash of the tint | Solid tint | | Hover | 11% gray fill | 24% wash | 5% darker | | Pressed | 16% gray fill | 28% wash | 10% darker | | Disabled | 4% gray fill, faded label | 12% wash, label at 40% | Tint at 40%, label at 50% white | Borderless has no fill in any state; see [Borderless](#borderless). In dark mode the gray fills use white (7% at rest, 16% pressed), and a pressed filled button gets slightly lighter. That matches how macOS lights controls on a dark background. A disabled filled button keeps its color, faded. It no longer drops to gray, so a disabled Save still reads as the primary action waiting for input. Keyboard focus draws the macOS focus band: a 3.5px ring outside the button plus a 1px ring just inside its edge, both in the button's color at 50%. Mouse clicks do not trigger it. ## Borderless A borderless button is only its label. It has no fill at rest, on hover or while pressed. Pressing darkens the label by 46 levels on every channel (it brightens in dark mode), and a disabled label drops to 50%. ```html ``` On an opaque background the label is the control accent, `#0088FF` (`#0091FF` in dark mode). Inside a vibrant surface it switches to `--p-control-accent-text`, a darker `#0078F0` that keeps thin glyphs readable over glass. In dark mode both are `#0091FF`. ## Vibrant Buttons that sit on a material (a menu, a popover, an alert) blend with the glass behind them. Add `.p-vibrant` to the element that paints the material and every button inside switches to the vibrant recipe. The desktop alert (`.p-desktop-modal`), `.p-popover` and `.p-menu` are vibrant already, with no extra class. ```html

``` | Style | On a vibrant surface | |---|---| | Default and Tinted | Black 7% plus black 12% in overlay blend, so the fill darkens with the glass. White 6% plus white 12% overlay in dark mode. | | Colored and Primary | The tint in `plus-darker` (light) or `plus-lighter` (dark). Pressed mixes in black 10% (white in dark mode) first. Disabled runs the same layer at 40%. | | Secondary and Destructive | The vibrant accent (`--p-vibrant-blue`, `--p-vibrant-red`) at 23% (20% in dark mode) with a vibrant-accent label. | | Borderless | The label moves to `--p-control-accent-text`. | The blend layer composites onto whatever paints the material. Put `.p-vibrant` on the element with the background, not on a transparent wrapper around it: the class makes that element its own stacking context, so a wrapper would leave the buttons nothing to blend with. Safari supports `plus-darker`. Chrome and Firefox don't, so light-mode filled buttons fall back to `multiply`. That is identical over white and a few levels lighter over light glass. Dark mode's `plus-lighter` works everywhere. ## Inactive window When a macOS window loses focus, its push buttons lose their color. Filled, secondary, destructive and tinted buttons all become the plain gray button with a primary label, in every state: 8% gray at rest, 16% pressed, 4% with a faded label when disabled. Borderless buttons keep their accent label. Inside a vibrant surface they turn into the vibrant gray button instead. Wrap the window in `.p-window-inactive`, the same class that grays the window's traffic lights and sidebar icons. ```html

``` The `data-window-state="inactive"` attribute does the same thing if your app prefers attributes over classes. Toggle the class or attribute when your app's window loses focus. Checkboxes and radios in the same window go gray too (see [Forms](https://puppertino.com/docs/desktop/forms/#inactive-window)). ## Dark mode Buttons flip with the rest of the page in dark mode. No extra setup, no button-specific class to toggle. If you retint a button, use a `.p-sys-*` color so the new tint flips too. The brand palette stays at its light-mode hex on both appearances. ## Accessibility - **Keyboard focus** shows the macOS focus band (3.5px outside, 1px inside) at 50% of the button's color. Mouse clicks do not show it. - **Reduced motion** removes the hover and press transitions. - **Reduced transparency** swaps the tinted variants to a flat opaque fill so the label stays legible. - **Increased contrast** adds a 2px border around every button. - **Windows High Contrast** hands the button over to the operating system's color scheme. - **Touch targets**: Regular and Large meet the 44px minimum. Mini and Small are pointer-only. ## Code ```html

``` The class works on `

Hello from Puppertino

Library

Welcome to Puppertino

Page title

A subsection

Hello

Hello in dark mode

Colors

Delete “Q3 Report”?

Unsaved changes

Sign In to Wi-Fi

Share “Q3 Report”

Q3 Report

No Messages

No Results

All Caught Up

Do you want to keep this new document “Untitled”?

Name	Kind	Size
Report.pages	Document	1.2 MB
Notes.txt	Plain text	4 KB
Design
Mockups.fig	Design file	48 MB
Icons.svg	SVG image	96 KB