Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
Visual Language
This is the single design requirement for Piik's shared Web/App interface:
control/surface selection, illustration, semantic colour, motion and guidance.
New UI work follows this file and the local /__tooltip-preview catalogue.
Media status owns which facts justify each status;
presentation lifecycle owns interaction
and playback. Neither an illustration nor its colour creates product state.
Use one stroke language for single concepts, small panel comics for causes and sequences, and literal scene objects for people, rooms and media. Glyphs do not form sentences. The same meaning and visual hierarchy must work in Chinese, English and pure-visual modes, in both themes and at narrow widths.
Piik's living room uses simple silhouettes, generous space, rounded controls and a small responsive bounce. Clear hierarchy and legible interaction keep the playful details easy to use. The copy guide owns its voice. The public introduction guide owns website and film hierarchy: shared identity, current product demonstrations and promotional composition. It applies the copy guide's audience and technical-detail layers.
Keep playfulness restrained: clean silhouettes, balanced proportions, quiet expressions and brief gestures. Keep the interface approachable; avoid pushing ordinary characters toward infant proportions, exaggerated grins, dense cute decoration or children's picture-book styling. This balance applies to all comic hints, status overlays and entry/error scenes.
Consistency governs meaning, cast and interaction, not identical compositions. Give each explanation a recognisable little scene: a welcoming hop, a curious peek or a character leaning into an action. Anticipation, a soft landing and staggered responses make movement expressive. Reuse drawing primitives and motion ownership; do not reduce distinct situations to one layout with a swapped symbol.
Layout And Input
Use spacing, alignment and type hierarchy to group UI facts. Write explanations as normal localized sentences; keep names, device labels, status and actions in their existing visual groups rather than joining them into dotted strings. A middle dot is reserved for short, genuinely peer metadata such as compact measurements or version details. It is not the default separator for headings, instructions, accessible descriptions or a label followed by an explanation.
Present a small shared living room: the television is the media stage, the couch and pawns make presence spatial, and the four-digit room code stays prominent. Decoration must clarify product facts without creating another state model. Universal digits, transport symbols, URLs and measured values remain literal when the user needs the data.
Functional controls use native buttons/inputs and localized accessible names. Pointer cursors identify actions, navigation and controls that change a setting; text inputs use text cursors. Read-only status and metric indicators keep the ordinary arrow even when tapping reveals an explanation. Keep these help-only triggers as native buttons for keyboard and touch access. Passive labels and illustrations also keep their ordinary cursor. Hover, keyboard focus and touch receive equivalent guidance. Keep information order and interaction ownership consistent across languages, themes and viewport sizes. Reflow or bounded scrolling must not hide a primary action, truncate an essential value, overlap controls or change meaning. Keep a compact value and its direct actions together when rows wrap, including the room code and its replacement confirmation. Let independent groups reflow; do not stretch short values to fill a phone row. Check actual control bounds around breakpoints, in both orientations and all presentation modes; page-level overflow clipping is not evidence that the content fits. Keep existing controls in their established positions as a room becomes active. Represent missing room identity with a passive placeholder in its own slot; do not move unrelated controls into that space to fill an empty state.
Control Selection
Choose by the user's task, then reuse its interaction and visual primitive. A sliding selection track shows a discrete choice; a range slider adjusts a number. Similar shapes do not make their responsibilities interchangeable. The catalogue renders production controls with sample data, including their meaningfully different variants and surfaces; dedicated playback and status previews remain linked from it. Keep a new control family discoverable there instead of leaving its only example in an ignored prototype. Platform-owned permissions and window chrome are verified in the actual platform, not imitated.
| Task | Control and existing owner |
|---|---|
| Perform an action or open a tool | Btn; use a stable caption and aria-expanded for disclosures |
| Turn a setting on or off immediately | SwitchItem; compact toolbar actions such as mute use a pressed Btn |
| Select independent options within a task | Native checkboxes or independent pressed Chips, such as held modifier keys; a selection awaiting Apply must not look like a committed setting |
| Choose a short, fixed mode | Shared .lr-toggle sliding selection; option chips/cards when individual choices need explanations, richer previews or wrapping |
| Switch related content pages | A named tablist with one selected tab and its associated panel; use the shared sliding treatment for short labels, including capture categories, and navigateTabs for Arrow/Home/End navigation |
| Pick a device or an item from a variable list | Existing named selector/menu; use source thumbnails when appearance helps identify the item |
| Adjust a numeric value | Range slider for quick adjustment, with a visible value; reuse NumberControl when exact entry or a wider accepted range is useful |
| Return within a room tool | Shared BackButton: left arrow and Back, with the same quiet dense treatment in settings and expanded reactions |
| Apply several settings together | A named preset tile/chip; allow no preset to be selected when the current values are custom |
Selection, expansion and pending operations describe different facts. Use the
appropriate native/ARIA semantics even when controls share their styling.
Shared control geometry and motion live in button.css; Btn selects their
variants. Use the regular size for standalone actions, compact for page/room
toolbars, and dense for secondary panel/list actions. These are defaults, not a
requirement for identical silhouettes: round icon actions keep equal width and
height, captions may form pills, and embedded tools may use quiet rounded
rectangles. Preserve proportions when space is tight; do not compress one axis
of a circle. Header utilities share compact alignment and icon scale with the
language track. Low-frequency help stays unframed and quiet; it need not carry
the outline or shadow of direct settings. Narrow layouts shorten captions or
spacing before changing that hierarchy.
Keep desktop App, language, theme and help together on the right. Narrow headers
retain one row with the brand/back action, signaling dots, App and More; language,
theme and help share that attached disclosure without duplicating their controls.
segmented-control.css owns the sliding treatment for language, mode selection,
tabs and native radio groups. Consumers supply selection and layout; they must
not duplicate the selected colours or press animation. Language choices keep
circular selection marks; settings and source tabs expand to fit their content
and available space.
Theme colours remain owned by palette.css. Rich choices, keyboard keys and
responsive media tools keep their task-specific layout without creating another
button or selection palette.
Button labels and drag handles are not selectable text, including on touch
browsers. Keep message text and editors selectable. Held-input controls own
release on pointer-up, cancellation, lost capture and surface blur; a browser
callout must not consume that gesture.
Tab navigation keeps focus in the tablist and preserves drafts/settings; the
navigation key must not become a remote keystroke or start capture. Existing
resource cleanup still applies. Value changes keep their domain owner's commit
behavior. A RowGroup arranges controls; it does not own their selection.
Surface Selection
Choose the smallest surface that supports the task's duration and relationship to the picture. Movable and detachable are separate capabilities, not upgrades that every popup should acquire.
| Task | Surface and existing owner |
|---|---|
| Read a brief explanation | Shared Tooltip; no settings or required actions hidden in a hint |
| Adjust a few contextual settings | Attached native popover with useAnchoredPopover; dismiss after use, no dragging or detaching |
| Work through related settings | Inline disclosure or tabs, as in SharingSettings; expand into page flow rather than cover the picture |
| Complete a task that blocks the page | Existing native modal dialog, such as share-failure help; contain focus and return it on close |
| Choose a source inside the television | TV-local nonmodal dialog; keep its own Tab loop, inner guidance before Escape cancellation, and return focus to the current share action on close. Surrounding room controls remain available to the pointer |
| Keep a room tool available while watching or working | FloatingPanel, as used for interactions and Host remote permissions; retain its position without reflowing the room |
| Use a tool outside the page | Optional usePanelWindow on capable browsers; reuse the same content/session, as with interactions, remote permissions and the docked remote keyboard |
Chat and voice share one settings entry beside their tabs. Returning from either
settings page or an expanded reaction palette uses BackButton, not a destination
name or content icon. Audio icons keep their direct microphone/listening toggle;
AudioVolumeMenu exposes the shared volume slider on mouse hover, keyboard focus
or touch hold. It uses the guidance timing constants and anchored popover owner,
replaces a hint with an actual control, and never widens the participant row.
Settings remain an explicit touch entry for microphone and master volume.
Persistent room utilities use the shared floating panel without reflowing the living room. The shell owns visibility, focus return, movement, resizing and viewport/keyboard bounds; contents retain their domain state. Support title-bar dragging, corner resizing and equivalent keyboard controls without a second placement menu. The couch's full interaction palette starts beside its chosen participant, stays open after sending and keeps its position when retargeted. One-shot settings and guidance retain their existing disclosures. Anchored menus use native popovers and shared viewport placement; a small parent panel must not clip their actions. Browsers without the Popover API use one shared platform polyfill installed before UI mounting; controls retain the same visibility, focus and dismissal contract. Escape closes inner guidance first, then the most recently opened floating panel, then theater mode; an IME composition must not dismiss these surfaces. The interaction window keeps its conversation and composer available while reacting. A current participant's message avatar or voice avatar opens a small attached palette with thumbs up/down and the two throwing props; one's own entry uses laugh and heart in place of throws. Throwing props keep the full palette's distinct card styling; compact buttons omit captions. More reactions expands the same curated choices on demand, with a labelled back arrow in the heading. Do not add a second roster or reflow the list. The native popover owns outside-click and Escape dismissal; sending keeps it open for repeated interaction. The couch retains its movable full palette. Both surfaces reuse target identity, reaction buttons and the existing send owner. Live reactions can appear briefly in the conversation surface without moving its layout. Retention and export details belong in settings, not beside every entry. Detachable tools reuse the same content in the browser's own always-on-top frame. Close, return-to-tab, movement and resizing belong to that frame; do not duplicate its controls in the tool header. Keep messages and text contrast primary; do not simulate transparent desktop content with a washed-out panel. Moving or detaching changes the surface, not the domain owner or protocol. Request the tool's current rendered size when detaching, within browser window limits. The native title bar replaces the floating panel's header; keep body spacing and control sizes consistent with the in-page tool. Reuse visibility, placement, dismissal and focus behavior through these existing owners; do not give each feature its own window manager. Different layouts are justified by task or available space, not by which feature was implemented last.
Keep the application language control's segmented Chinese, English and visual shortcuts. When additional catalogs exist, insert one language menu after the visual shortcut; all extra languages share that slot. Show the selected language's short label there and native names inside the menu. Reuse the sliding selection, rounded paper panels and control motion. The native popover owns visibility, outside-click dismissal and Escape; the language control owns menu navigation, focus and viewport placement. Keep touch rows large and long lists scrollable. Locale labels belong to the shared registry. Use a globe and chevron for the unselected picker, and each language's own full name in the menu, following W3C language-navigation guidance.
Guidance
Help-only indicators toggle their guidance on click or tap and dismiss on a
second activation, outside tap, Escape or focus leaving. Touch long-press opens
guidance after a 500 ms hold on both help indicators and action controls,
without triggering the action on release. Action controls keep their direct
short-tap action. Tooltip owns these interactions; pages do not add their own
open state or timers.
An actionable sharing failure reveals its status guidance once without moving focus. Keep troubleshooting on the status indicator's direct action; do not add a permanent caption beside the light. The shared tooltip retains dismissal and can be reopened through its ordinary hover or touch-hold interaction.
Mouse hover opens after 500 ms of staying on the trigger; passing through or operating a control cancels that pending hint. Keyboard focus and explicit help activation do not wait. Keep the open panel hoverable for reading, with a short crossing grace; Escape, clicking the panel or clicking elsewhere dismisses it. A panel click only dismisses guidance and never activates an underlying control. Keep the comic compact without reducing caption legibility. Player hints prefer available space beside or below the television; when that does not fit, clear the whole playback bar. A wrapped option row is also one area to avoid. Status, headers and bottom-of-picker controls prefer below; other controls prefer above. Flip to fit the viewport and keep the caret aimed at the trigger. Placement and hover timing belong to the shared component. Constrain oversized hints to the visible viewport and let their content scroll without dismissing the panel or clipping its caret.
Add a tooltip when it explains an action, a limitation or a status that needs context. Plain names, decorative participants and self-explanatory text do not need another popup. Keep participant details on their existing click action and state explanations on the dedicated status indicator.
When a nickname is clipped, the shared tooltip reveals its complete literal text in every language mode, without a comic or repeated role/status labels. Show this only after detecting actual truncation; resize and name changes must recheck it. Preserve hover, keyboard and touch-hold access, and the participant's existing click action. A complete or wrapping name needs no extra focus stop or popup. If a status tooltip already wraps the row, add the clipped name there rather than nesting another tooltip.
Tooltips, state overlays and entry/error pages reuse the same illustrative scene in every mode. Chinese and English add a concise caption beneath it; pure-visual mode keeps the scene and its playful pictograms as an explicit alternative. Literal names and addresses keep their exact text. An invitation explanation retains its link scene; simply revealing a clipped name needs only the name. Do not substitute an unrelated action just to fill a tooltip. Illustration and caption explain the same action or current fact, with one tone and motion owner. Mount scenes only while their tooltip or overlay is shown; captions remain readable throughout.
Metric icons and hints share the metric-presentation.ts definition in details
and overview headings. Frames, packets, jitter and audio repair have distinct
symbols; related time measurements keep a clock with a scene identifying the
measured stage. Illustrations explain a metric, never invent its current value,
threshold or quality verdict.
Sharing And Playback
Shared buttons and chips use pill shapes and a quiet lower edge.
Standalone buttons, chips and option tiles lift 2 px on hover or keyboard focus, sink 2 px
on press, and spring back over 260 ms on release. Selected and unselected states
use the same motion; selection changes only their colour and outline.
Inputs and option tiles share softer corners. Press feedback uses the shared
motion values in button.css and releases the lower shadow. Captions inside
sliding tracks stay centred on their selection surface during hover and focus;
presses retain the shared feedback. Keep icon,
text and control dimensions intact: scaling the whole button shifts off-centre contents
sideways and changes their stroke weight. Do not add a separate icon displacement.
Keep filled buttons' border and face in the same colour state; a bright inset
rim must not look like a gap between them. Keep a distinct focus ring and a
persistent selected state; disabled controls must not pretend to activate. Reduced motion keeps
the colour, outline and selected position without decorative displacement.
The shared button uses the same pressed value for aria-pressed and its selected
treatment; active state remains distinct from hover in both themes.
Disclosure buttons keep a stable visible caption, while their expanded state and
accessible action describe opening or closing. Related tool captions use the same
grammatical form: name the feature rather than mixing feature names with instructions
to show them. Neutral panel borders stay quieter
than the controls inside them; nested diagnostic panels retain their softer fill.
Keep room identity, invitation and admission controls ahead of expanded topology
and connection details, so inspecting a route does not displace room actions.
Sharing and local playback controls use the same quiet, compact button treatment. The Host's persistent dock stays below the picture; the Viewer's playback bar belongs to the video. Their similar appearance does not equate broadcast pause with local playback pause. A waiting overlay dims the complete picture, including behind the playback bar; its message uses the space above that bar. Keep the primary status readable on narrow screens; optional waiting copy yields first. Microphone mute, sharing pause, source replacement and stop remain direct actions; stop retains its danger treatment. Group direct sharing actions in one centred dock below the television, above the couch. Keep pause/resume and stop adjacent; use an internal separator for the settings and remote-permission entries. Preserve that order and grouping on narrow screens without splitting the dock into separate floating surfaces. Room invitations, admission and chat retain their room scope; they do not become sharing settings merely because they use a similar control. One inline settings panel uses picture and sound tabs with the shared sliding two-option control. Picture presets lead; a fine-tuning disclosure contains picture limits, preference and video encoding, keeping configured limits visible when closed. In sound, source-audio inputs precede source-audio quality; room microphone settings stay in the voice panel. Presets remain available before sharing starts. Switching tabs does not reset values or restart media. Keep the less frequent connection options in a shared disclosure below the tabs. Expand in page flow, pushing later content down instead of covering the picture or participants. Related fields share a row where space permits and stack on narrow screens. Avoid another permanent row of settings cards. Numeric quality inputs retain the accepted capability range; sliders offer a labelled common range for quick adjustment. Values outside its range or steps show a custom-value row instead of an inaccurate slider position. Returning to the nearest available common step is an explicit action; rendering, focus or reopening never changes the value. Derive this presentation from the current value, without a second setting mode. Shared presentation stays separate from the existing setting/resource owners. The microphone comic depicts microphone input gain; the Viewer's listening-volume comic remains a different action. Room voice retains one bottom toolbar: open/join and close/leave share its right action position; microphone and listening controls appear to the left after joining. Use the shared media-control styling for both states. Missing browser microphone capability disables capture with a contextual explanation, without disabling listening.
Playback follows the shared playback owner. Keep related controls together at the picture's lower edge: local playback and sound, remote input, viewing options, then window modes with fullscreen last. Common actions remain directly available; detailed preferences use an anchored popover. A narrow player keeps one compact row, including sound, remote input and window actions. Picture fit and rotation move to the same attached settings at that width, reusing their controls rather than duplicating visible actions. The playback surface is lightly translucent over the picture. One visibility owner hides the complete surface. Grants, pause and source changes do not move the bar or resize the picture. Remote input retains its local bezel pull. Playback settings own on-screen chat appearance and connection preferences; chat settings own records, and voice settings own microphone processing. Viewer settings prefer space below the picture without resizing it. Use equal-width choices and stack groups on narrow screens. Fit, proportional crop and stretch change local display only, separate from the Host's picture settings. Persistent interaction and remote-permission tools may use the shared floating window; the remote keyboard docks outside the picture and can detach on capable browsers. One-step actions and brief adjustments do not need movable windows. Touch controllers default to direct touch without a cursor. A draggable mini mouse expands on tap, with its cursor spaced above and to the left; one pointer position drives both. The existing viewport pans the picture to leave room for the mouse at its edges. Added blank space is bounded by the tool's footprint, and the cursor stops at the source picture's edges. Two-finger pinch and pan move the picture beneath the full mouse, reanchoring its local source target without remote input. The compact trackpad retains its two-finger scrolling at normal scale. A separate button minimizes it and restores the selected touch mode; the compact trackpad cursor remains an optional local preference in playback settings. Only the mini mouse tucks away after resting at a picture edge, using the player controls' idle delay. The wheel shares middle-click, scrolling and held middle-drag in one target. Expanded buttons, scrolling and pointer movement share the existing input grant and pointer geometry; the keyboard keeps its separate docked surface.
Visual source choices (windows, screens and cameras) share named thumbnail cards, including their focus, hover and refresh treatment. Thumbnails fit the whole frame at its original aspect ratio within the card; constrain the media box itself so portrait and wide sources cannot enlarge its layout or be cropped. Keep both orientations represented in the source-picker preview. Microphone selection uses device names in a compact selector. Shared enumeration does not make these two selection tasks visually interchangeable.
Cast And Objects
The brand mascot keeps its own identity, separate from ordinary participants. Participant characters should leave room for that distinctive presence.
The App badge and favicons derive from one SVG:
a dark navy tile, warm white television outline and small gold sparkle. The
unfilled television, antenna, feet and wink keep the proportions of BrandMark;
do not give the badge a filled case or a separate screen. This palette stays
fixed across system themes. Let the television fill the tile with optical
padding so the surrounding tile does not make the mascot look undersized.
At 16–24 px, strengthen the outline and open eye, and omit the decorative
sparkle and tile rim. Keep the antenna, feet and wink at every size. Render
each export at its target viewport; check actual 16/24/32/48 px on light and
dark backgrounds rather than judging only an enlarged master. This follows
Microsoft's small-size silhouette guidance
and GNOME's detail guidance.
Inline brand
marks keep the same wink identity and outline. Their standard gesture keeps the
body and feet still: the face appears with both eyes open, followed by a short
antenna sway, wink, then two gold sparks. The
shared brand animation
owns timing, sparkle origins and trajectories for the product, website and
film closing card; looping presentations leave a quiet interval between gestures.
Reduced motion shows the static wink. A held film ending continues the complete
shared gesture, while the wordmark and address remain still.
Their stroke inherits the local surface's text colour:
dark ink on light surfaces, light ink on dark surfaces, including deliberately
light panels within a dark page. Gold sparkles remain a brand accent in both
forms. Do not assign black/white outlines independently at each call site.
The badge identifies App packages, browser tabs and search results. In-page
branding and the README mark keep the unboxed outline;
changing the badge does not restyle the UI, wordmark or illustrations.
| Meaning | Representation |
|---|---|
| The person using the pictured action | Green pawn (YOU / --you), in every panel |
| Somebody else | Blue pawn (SKY), or another distinct non-green illustration colour |
| Host role | Gold crown above the head: rounded three-point outline, dark gold edge and a quiet lower rim; the standalone absent-Host symbol uses the same outline, unfilled and dashed |
| Shared or watched media | Small television, including antenna, body and feet |
| Browser application | Browser chrome around content; not a second design of television |
| A captured window or display | Window title bar or display stand, with the shared media metaphor kept distinct |
| A camera source | camera identifies the alternative picture source. Source/playback sound retains the speaker metaphor. |
| Room text and reactions | chat opens the conversation, danmaku controls its optional picture overlay, smile identifies reactions and send submits the chosen content. These do not represent media transport or voice. |
| Room voice | microphone / microphoneOff identify input state; headphones / headphonesOff pause or resume room-voice listening, while speaker / speakerOff mute one person locally. Input, playback and forwarding remain independent. Toggle names stay fixed. The microphone's green fill shows measured input after gain, not the configured gain percentage. Participant rows keep avatar, name and microphone aligned; the status symbol has an accessible name and shared tooltip instead of a repeated on/off sentence. Measured speech fills that symbol and colours its outline green, without adding a connection-like dot. An enabled input alone is not speaking evidence. Opening the channel and opening a microphone stay separate actions. The Host has labelled open/close-room actions, with stop and danger styling for closing everyone's voice; a Viewer's door leaves only their own voice participation. Joined membership does not use a network-strength symbol. |
| Attended desktop control | mouse identifies keyboard/mouse control, distinct from sharing or playback. Permission copy stays literal; an active control marker describes the grant, not media connectivity. |
| Floating utility placement | grip marks a draggable title bar; corner handles resize the window. Closing a panel hides its presentation, not its room session. |
| Server forwarding media | A server on the media path; opening a Site alone does not imply SFU |
These are identity/object colours, not status. A green pawn remains green in a failed scene; a successful scene does not turn other people green. Real roster identities use the shared UUID colour function to generate stable hues, lightness and chroma outside the upholstery/crown's amber range, not a fixed list or the illustrative "you versus others" palette. The same identity keeps its colour across surfaces, themes and roster changes, without colour-assignment messages. Similar colours remain possible; names and self/Host marks identify people. Actor positions and identities remain stable from the first panel to the result.
Room pawns, tooltip/status comics and introduction participants use
a round head, half-oval body and two restrained eyes. Reuse the shared
figure and face geometry in product illustrations so expressions stay inside
the head as it scales. Larger scenes can add a small lean; small status panels
may omit facial detail to keep the action clear. Compact comic pawns stay small
and handless: use gaze, body lean and short hops to express their action. Keep
their scale consistent with neighbouring scenes in the same family. The relevant
door, credential or media object carries the explanation; people provide scale
and a response. Leave space around them so the action is legible. Use the
room-admission examples in /__tooltip-preview as a reference for compact
proportions and detail, while giving other subjects their own appropriate scene.
Large introduction illustrations may use small floating round hands to hold a prop.
A held gamepad is a scene prop; a separate role crown identifies the host and
moves with the body. Its gold is an identity colour,
not a warning or achievement. The share control retains its
cast icon. The cast represents friends sharing games, drawings
and other screen content. Exploratory figures are not alternate
participant identities. Keep the brand mascot distinct.
Participant state belongs to the shared pawn: light headphones indicate joined
room voice, resting around the neck when listening is paused. The microphone
boom extends toward the mouth when open and folds up when muted, independently
of listening. The toolbar's shared mouse glyph sits
centred on the body for an approved remote-control participant, regardless of
input device. These marks follow the existing membership and control grant;
they do not assert speech, input activity or media-route readiness.
The couch has a back, seat, arms and feet. A full room reflows into rows of seats without hiding people or requiring horizontal scrolling. Topology preserves each participant and actual parent edge at a readable scale; reduce spare spacing, then use a vertical outline when depth exceeds the available width.
Couch upholstery uses the fixed warm orange/yellow --couch / --couch-dark
palette. Never draw upholstery from the participant palette or randomize it by
room. Keep automatic participant colours outside the upholstery's amber/orange
range and the crown's gold; check the generated range against both objects in
light and dark themes. Fixed illustration colours remain illustration tokens.
The crown retains a bright gold fill with a dark gold edge.
Figures and exterior upholstery use flat fills without outline strokes.
Use differences in tone, spacing and name tags to keep people readable; retain
only the few interior seams that clarify cushions. Apply this convention to
the website and README cast as well as the product UI.
Symbol Reference
This reference applies to controls, status strips, comics, overlays, document titles, placeholders and public product demonstrations. A symbol keeps its basic meaning across those surfaces. Its nearby label identifies the affected object; it must not silently acquire a different measurement or permission. This reference describes functional meaning in context, not exclusive ownership of every shape. Decorative lettering, welcome ornaments and shared screen content do not become controls or measurements by using a familiar symbol.
Glyph owns small-icon geometry and the accepted
GlyphName union. Use it for controls and embedded comic symbols; reuse MiniTv,
Pawn, InviteLink and the other shared scene objects for illustrations. Select
existing meanings before adding an icon. A new meaning needs a row here and a
rendered example in the existing catalogue. A typo or missing icon must fail
type checking rather than silently render a warning triangle.
| Meaning / 含义 | Symbols | Use and boundary |
|---|---|---|
| Participants and room / 人与房间 | users, couch, door |
People, shared room, room entry. Use the shared pawn for a person and HostMark for Host authority. |
| Create / 创建 | plus |
Create the named object. An empty room-code frame uses this action before the room exists; the resulting code replaces it in place. |
| Shared screen / 共享画面 | tv, MiniTv, 📺 |
Media or its sharing source. The TV beside the Host name identifies the source; the crown on a person identifies the role. |
| Start and choose a source / 分享与选源 | cast, share, switchSource |
Start sharing, capture a screen, replace the current capture source respectively. A captured window keeps window chrome or a display stand. |
| Capture source / 采集来源 | window, display |
An application window or a whole display; these nouns remain distinct from the source-switch action. |
| Invitation URL / 邀请链接 | link, InviteLink, linkOff |
A URL and its disabled/revoked form. Keep the chain when copying or rejecting it. Copying is local; a send-to-chat scene is a separate action. |
| Credential / 凭证 | key, password dots |
Site passphrase or room password, identified by the field label. Room-code admission with a password shows both fields. |
| Restriction / 受限 | lock |
Restricted entry, concealed password or a setting fixed by availability; show the affected object. A lock never promises anonymity or secure media. |
| Site and public entry / 站点与公开入口 | globe |
Browser/Site entry or code-based public entry. It does not claim internet reachability. |
| Preferred destination / 默认去处 | star |
A user-selected default, such as the App's startup Site. It is a preference, not authorization or connection health. |
| Connections / 连接 | network, branch, signal, wifiOff, server |
Topology, branching, signaling, disconnected signaling and the named server. The header's three equal circles show only signaling state: three steady green for connected, two animated yellow for connecting/recovering, one red for a failed connection, all grey for offline. Active dots have equal brightness; this is neither a signal-strength measurement nor a media-quality claim. The television lamp owns sharing/viewing state. A server on a media path means forwarding; a Site backend or control-link server alone does not imply SFU. An invitation chain does not represent signaling. |
| Playback / 播放 | play, pause, stop |
Play/resume, pause, end. The control label states whether it affects local viewing or the Host's share. Stop is distinct from a paused or idle room. |
| Audio / 声音 | speaker, speakerOff |
Audio and mute/no audio, qualified by the source or local playback label. A source track's presence does not establish delivered sound. |
| Size and viewing mode / 尺寸与观看模式 | expand, contract, pip, pipExit, theater, theaterExit, fitContain, fitCover, fitStretch, rotatePicture |
Expand/restore, enter/leave picture in picture or theatre mode; contain, proportional crop and stretch change only local picture fit. Picture rotation switches the local landscape/portrait view. The same size symbol can accompany a resolution measurement. |
| Local actions / 本地操作 | copy, save, pencil, eye, eyeOff |
Copy, save, edit, reveal and conceal the named object. An action icon does not prove completion. |
| Text appearance / 文字外观 | textSize, opacity |
Relative text size and opacity. These are local display preferences, not message delivery states. |
| Repeat and disclosure / 重试与展开 | refresh, chevron, arrowRight, arrowLeft |
Repeat/refresh, expand/collapse, proceed/enter and return. Direction follows the control's action; no arrow alone establishes delivery. |
| Transfer and upgrade / 传输与更新 | arrowUp, arrowDown |
Outbound/inbound or upload/download, qualified by the adjacent label. An explicit update label may use the upward arrow for upgrade; neither arrow is a connection-quality rating. |
| Diagnostics / 诊断 | cpu |
Technical diagnostics in the labelled diagnostic control; in metrics the same processor identifies encoding work. The surrounding control or measured field states the scope. |
| Help / 帮助 | help, book |
Open product help or read a guide, respectively; current build identity belongs with this low-frequency information, separate from media settings and App connection state. |
| Settings / 设置 | sliders, mountain, balance, frames |
Settings, preserve image detail, balanced preference, preserve frame rate. The frame-rate preference uses the same frames as the measured value. |
| Progress and result / 进度与结果 | loader, alert, check, x |
In progress, a problem, confirmation/positive result, cancellation/negative result. The status owner supplies severity; the shape alone cannot set it. |
| Theme / 主题 | sun, moon |
Light/dark appearance in theme controls. A moon in an idle-room scene means rest, with the idle scene providing that context. |
| Welcome decoration / 开场装饰 | gamepad, popcorn, clapperboard, trophy, gift, flag, heart, bulb, zap |
Games, snacks, film, achievement, gift, next stop, affection, discovery and energy. These may decorate the welcome line, never a measured speed, failure or connection verdict. |
Metrics use METRIC_PRESENTATION in both summaries and details. Labels, units and stage-specific comics distinguish related values; views do not choose their own symbols.
Topology hover and keyboard focus use neutral outlines; selection adds a heavier outline and text weight. Connection colours remain owned by route/readiness facts, so interacting with a node cannot look like a connection-state change.
| Measurement / 指标 | Symbol | Boundary |
|---|---|---|
| Frame rate / 帧率 | frames |
Video frames per second, including capture/input frame rate. |
| Packet loss / 丢包 | packetLoss |
Missing network packets, including audio packets. |
| Dropped frames / 丢帧 | frameDrop |
Discarded video frames in the stated observation interval; never substitute packet loss or a cumulative total under the same interval label. |
| Jitter / 抖动 | jitter |
Variation in arrival timing, including audio jitter. |
| Audio concealment / 音频补偿 | audioRepair |
Missing audio concealed by the decoder. |
| Rate / 速率 | gauge, speaker for audio rate |
Bitrate or outgoing rate; the unit remains visible. |
| Duration / 耗时 | clock |
RTT, encode/decode time, freeze duration, playout or buffer time. The label and comic identify the measured stage. |
| Freeze count / 卡顿次数 | pause |
Count of interrupted video progress, distinguished by its metric label from intentional pause. |
| Encoder and codec / 编码器与编码格式 | cpu, puzzle |
Processing implementation and encoded format respectively. |
Text-only surfaces retain the same meanings:
| Surface | Standard and owner |
|---|---|
| Activity in document titles | Title catalogs: 📺 sharing/viewing, 🛋️ ready room, 💤 idle, ⏳ waiting/starting, ⏸️ paused, ▶️ waiting for playback, ⏹️ ended, ❗ unavailable. Secondary decorations cannot replace this leading meaning or imply new progress. |
| A problem beside an activity | Media status supplies ⚠️ from actual facts; document-title only composes and rotates titles. |
| Default names | display-name owns 📺 for the sharing source and 👤 for a Viewer in visual mode. Preserve user-entered emoji names as data; never infer role from their characters. viewer-presence owns duplicate-name suffixes. |
| Visual-mode shortcut | ✦ in the language control and its documentation; not a success or quality mark. |
| Input placeholders | Four slots represent the four-digit room code. Password dots mask a field; their illustrated count imposes no password length. Numeric samples reuse the actual field's --mono typeface and weight. Real inputs retain localized labels. |
| Unknown values | — means unavailable/unknown, never zero or a healthy result. Keep exact values and units whenever known. |
| Capability values | ✓ / ✗ answer the adjacent boolean capability, not whether an entire route or share succeeded. |
| Shortened text | … means truncation. Preserve the full nickname/URL for reading and copying; never turn an exact value into a decorative code. |
| Welcome cipher | The locale entry owns its two meaningful symbols; WelcomeLine renders their pixel words. They are decoration, not hidden connection state. |
Feedback Composition
Choose the illustration from the operation's scope and the caption from its actual state. Each feedback region has one principal illustration; a comic does not need a second mascot or decorative spinner. The header's brand mark remains navigation identity. Keep an actionable play symbol or an exact progress value when it helps the user proceed or understand the operation.
Review the visible page as a composition, including open tooltips: give it one expressive focal illustration, rather than repeating the mascot in a heading, card and status. A small navigation mark may coexist with a contextual mascot; it is not another focal illustration. Remove decorative duplicates before changing the shared character or adding visibility state. This applies the illustration guidance: support the task and use lighter icons or copy when another drawing adds noise.
| Context | Illustration and literal content | Playful caption |
|---|---|---|
| Page loading or site access check | The shared wink mascot with the actual loading operation; no room or media-path claim | None |
| App room startup | The shared wink mascot with the actual operation | One secondary waiting caption |
| Confirmed App readiness | Wink mascot with literal readiness in dedicated feedback or its tooltip; an inline summary beside an existing main brand uses a status icon. Neither implies an active media route. | None |
| Source listing/start/switch, room joining, media setup/recovery, waiting for the Host | The corresponding comic with the current status; only the existing state owner can declare waiting | The same waiting pool while the wait exists |
| Error, limitation, pause, ended room or required user action | The corresponding comic and clear reason/action; settled movement keeps that verdict readable | None |
| Small controls, tooltips and inline results | Existing action/status icon and contextual guidance when needed; retain direct actions | None |
The shared LoadingStatus, StageOverlay and WaitingCaption apply this
composition. Routine loading does not opt into playful copy automatically.
Do not infer waiting from a chosen drawing, mascot visibility or animation flag.
Healthy playback stays visible during control reconnection; this rule does not
create another overlay. An idle room awaiting a new share differs from a closed
room. In pure-visual mode keep the same illustration and accessible operation
name, with no waiting text. Welcome ciphers retain their separate role.
At compact player sizes, omit the optional caption before shrinking the comic
or the actual status into illegibility. The existing visibility policy suspends
hidden captions; viewport size does not become product state.
Playful Copy Lifecycle
Locale files own independent pools; the shared selection and rotation owner and its React adapter provide selection, timing and visibility. Keep one secondary playful line in an operational page's main content, with no duplicates in subpanels. Review the whole composition before adding another caption.
Website/App welcomes select one entry immediately and keep it during that visit. Tab titles retain one variation per actual activity, without a timer. Ordinary rerenders and metric updates do not draw another entry. A welcome's text/visual switch preserves its selected entry. Language changes use that language's pool, never a cross-language array index.
Only App room startup and media waits rotate their secondary caption: show one immediately, then change it every fifteen visible seconds. Changes of the literal status within a continuous wait do not redraw the caption or reset its clock. Draw without replacement until the pool is exhausted. Hidden surfaces stop advancing; on return, keep the line for a full interval. Reduced motion retains a static line. Unmount or an ended wait retires timers and listeners. Empty pools omit the decoration; one-entry pools stay static. Real completion never waits for copy or animation. This cadence is a product choice, not measured progress.
Each language maintains independent contextual pools without equal counts, paired translation keys or a fixed total. Contributors can add a locally natural entry without inventing equivalents in other languages. Keep operational labels in the ordinary translation contract. Welcome ciphers attach meaningful symbols to the selected entry, rather than depending on a global numeric correspondence. Pure-visual waiting keeps the shared animated scene.
Actual status, error reasons, paused/ended states, required actions and slogans remain literal. A title retains its primary activity and any applicable warning. Waiting decorations never invent steps, remaining time or success; they are excluded from live status announcements. Small controls retain concise labels and their existing motion. Graphic composition still follows its own contextual review; this copy policy does not require a mascot or a new tooltip everywhere.
| Existing surface | Copy coverage |
|---|---|
| Website welcome, App launcher, sharing entry | One welcome per entry; the App's visual mode renders that entry's cipher. |
| App room startup and media waiting | One slowly rotating caption according to feedback composition. Ordinary page loading and access checks use literal status only. |
| Browser tab | Sharing, watching, starting, ready-to-share, not-started and waiting states may append one stable variation; room identity, literal activity and warnings remain visible. |
| Error, pause, ended state, required action, tooltip, small control | Keep the existing literal message and contextual graphic; no rotating caption is added. |
Panel Composition
Choose panels by what the explanation asks the reader to compare:
| Composition | Use |
|---|---|
| Two panels | Default for action → effect or condition → outcome. The left supplies the action, credential or context; the right explains its consequence. Examples: copying an invitation, pausing playback, entering with a room code/password/invitation. |
| One wide panel | One ongoing or settled scene without a before/after comparison, or a continuous spatial relationship that a divider would break. Examples: waiting for the Host, an unavailable source, a network round trip. Width alone is not a reason to use it. |
Use the same composition and panel roles within a semantic family. Room-entry credential hints all use two panels: accepted credential on the left, access to the room on the right. The door scene explains admission; it does not claim that the user is changing privacy or has already joined. Vary the small gestures and useful props, not the reading order. Keep full-scene states and metric diagrams in one panel when splitting them would only duplicate the scene or interrupt its relationship. More than two panels require distinct steps of a real sequence that cannot be explained clearly in two; do not invent stages to fill extra panels.
Semantic Colour And Shape
App, website and documentation use the shared surface palette in
src/client/ui/palette.css: a fresh pale canvas, warm white paper, blue-grey dark
surfaces and clear text contrast. Source selection follows the same theme.
Reserve green for cast identity and semantic state, not the general canvas or
hover fill. Light mode uses blue for actions, focus and selected controls;
dark mode keeps navy surfaces with soft-white selection highlights and navy text.
Primary actions such as starting a share, joining and confirming retain their
blue fill and white foreground in both themes; theme selection must not erase
their identity. The active remote-input outline uses that same fixed blue;
suspended input uses the muted state. Use the shared foreground/background pairs
for both themes.
Selected choices, including sliding segments and language shortcuts, use the
shared --control-selected / --control-selected-ink pair and accent outline.
Unselected hover uses --control-hover. Subtle surface highlights
and shadows add depth without changing control geometry or press feedback.
Gold upholstery, illustration and badge artwork retain their own palettes.
The App terminal keeps its user's terminal background and palette. A compact mascot/title block identifies the App and build; state, addresses and available shortcut keys form separate reading levels. Use terminal-theme blue for links and actions, neutral rules, and the same success/wait/failure colour meanings. Preserve monochrome output and compact layouts without changing their behavior.
Use the semantic theme tokens in src/client/ui/palette.css. Status colours
keep their meaning independently of control selection and focus. The shared
comic-presentation.ts maps meanings to those tokens for tooltip outlines,
carets, result panels and verdict marks. Do not choose independent hex colours
or animation rules inside an individual scene.
| Meaning | Token / code tone | Panel and symbol |
|---|---|---|
| Explanation, preference, ordinary action, intentional closure or unknown state | Neutral ink / off |
Neutral panels; illustrate the action/object without a success stamp |
| Confirmed completion or delivered media | Green --live / live |
Neutral before, green result; check or completed object |
| Still usable with a limitation, unavailable optional capability, or intentional media pause | Amber --warn / warn |
Neutral before, amber result; limit, pause, lock or unavailable mark on the affected part |
| Confirmed failed or blocked action | Red --danger / bad |
Neutral before, red result; cross, broken path or other explicit failure mark |
| Work in progress or awaiting an action/frame | Blue --busy / busy |
Neutral before, blue current/result panel; connection, progress or play symbol |
Recovery retains amber because service is interrupted while work continues. Waiting for a Host and unknown observations remain neutral. A control's prospective action is not proof of success: opening details, switching theme, adjusting volume or offering P2P stays neutral. Actual copy feedback can change that same hint to green or red, using the existing operation result.
Review meaning at the call site. A current admission badge shows the credential accepted by room access. The private-mode control instead shows restricted code-only entry with a closed door; its meaning must not change to an invitation action merely because no room password is set. This room-entry rule is separate from media-route privacy. Password input is not proof of admission; copying writes to the local clipboard and does not send to a friend. An audio track's presence does not establish a locked control or delivery to another device.
Only the result carries the semantic accent; a single panel carries the current condition. Tooltip outline and caret use that same tone in Chinese, English and visual modes. Neutral uses theme ink, not literal white. Keep paper fills quiet; do not tint the whole scene green/yellow/red. Meaning must also survive without colour through objects, symbols and accessible localized names. Never show celebration or a completed live path as the verdict of a failed or unavailable operation.
A missing optional feature is not a failed media path. A rejected PiP request is failure; lack of PiP support is a limitation.
Motion Grammar
The brand mascot keeps its body still: antenna twitch, wink, then two sparkles.
Web/App and website identity marks share site/assets/brand-motion.css.
An entrance draws the shell once and starts the gesture only after the last
stroke completes; loading repeats the gesture without redrawing the shell.
Page readiness never waits for this decoration.
| Presentation | Rule |
|---|---|
Action demonstration (demo) |
Explain an action with a short gesture and a readable hold; repeat while displayed |
Work actually continuing (progress) |
Repeat a gentle connection/recovery beat while that state exists |
Settled success, failure, limitation, pause or idle (still) |
Keep the result readable while a related character or object moves; gestures loop without re-running the actual operation or changing the verdict |
Demonstrations and progress share the existing 3.2-second comic beat. The main action belongs in its first half, followed by a readable hold; small internal staggering is allowed. Keep one focal gesture at a time; other characters can answer it with a delayed reaction. A small action and a readable pause can carry the whole explanation; extra movement needs a purpose beyond making the scene busier. An explanatory slider describes purpose and available range, not its live numeric value. Decorative sparkle must support the pictured action, never fake current success.
The shared comic presentation owns repetition for tooltips, overlays and standalone results; scenes inherit its repeat count. Previews use the same rule, without their own animation overrides. Closing guidance pauses and unmounts its scene. The panel entrance plays once; its characters and objects keep moving while shown. Settled scenes repeat their quiet subject gesture; real progress repeats for its state's lifetime.
Reduced motion uses each scene's explicit informative static pose. Disabling animation alone is insufficient if the base SVG hides the result or shows a misleading starting pose. Settled facts stay visible during decorative movement. Static styling is scoped to its SVG; one still tooltip must not freeze another progress scene. Action demonstrations play forward, hold their result, then replay; a direct cut back to the opening pose is acceptable. Seamless loops are optional. Do not add a reverse action, extra bounce or fade just to match the first and last frames. Natural blinking, hopping and peeking can return to rest as part of the gesture. Keep movement brief and give the explanation quiet time.
Every comic surface, including overlays and error pages, needs visible motion in its subject: a paused scene's steam rises, a loose cable sways, or packets advance toward a bottleneck. Whole-scene entrance, blinking or sparkle alone does not satisfy this. Settled result marks stay readable during that movement. Changing the comic's meaning starts its animation afresh; changing a caption, language or numeric value alone does not. The preview's reduced-motion setting uses the same explicit final poses as the system setting. Check scenes in isolation, including settled overrides and quick re-entry while a tooltip is exiting, so another mounted scene cannot hide missing CSS or a finished animation. Reduced-motion rules must outrank settled-motion overrides. Also check the actual controls together, in every relevant property combination. Judge motion at its displayed size: a changing transform on a tiny figure can still look frozen. The default scene catalogue does not cover a Pill's settled override or missing preview states by itself.
The tooltip panel itself uses the same restrained entrance/exit for every tone. Replay belongs to opening/hovering/focusing the whole control, not just its SVG. Ordinary controls keep their icons visible during hover and keyboard focus; surface colour, lift, focus and press feedback carry the interaction. Reserve icon drawing/replay for primary actions such as starting a share or joining a room, and for explicit state-entry feedback. The whole control owns the trigger. Stroke and solid drawings share one total duration and easing; stroke count must not lengthen the animation. Disabled controls and passive status icons retain their informative pose; busy indicators retain their progress beat. Do not add a per-scene timer or another interaction/state owner. Outside status comics, the brand mascot and participant figures may blink or glance occasionally; a pictured screen can guide the Host's gaze. Keep eye gestures and small body leans brief, separated by long pauses and offset between people. A participant's UUID seeds the cadence; align its phase to wall time in every view, including later mounts and return from background. Names, roster order and the observer's role do not reseed it. Device clock skew bounds cross-device precision; cosmetic motion adds no signaling or media state. They express personality independently of connection feedback. Follow the system's reduced-motion preference, keeping a natural, open-eyed pose when enabled; participant gestures have no separate product playback control. Status comics still follow the table above.
Introduction artwork is separate from product status. Website/README scenes may repeat a short action with a generous pause. Keep broad movement to one or two focal elements; small participant gestures follow the quiet cadence above. Provide a pause or hide control for automatic loops, and a useful static pose for reduced motion. Product-state comics still follow the table above.
Entry screens may carry one quiet, original welcome line in Chinese or English text mode. Pure-visual mode pairs familiar pictograms with static pixel pseudo-lettering tied to the same line. Hide that visual cipher from assistive technology; the ordinary text sentence remains readable. Switching between text and visual mode preserves the selected welcome entry; selection follows the shared lifecycle. The line never replaces an action, error, loading message or connection progress. Keep it on one line, apart from the actions; primary controls take precedence when space is tight. A clipped line may pan once to reveal its end; fitting text stays still. Pause with the copy's existing visibility owner. Reduced motion keeps the text stationary and manually scrollable instead of discarding the hidden words.
Ownership And Incremental Review
- Existing status/operation facts outrank the scene default. Reused
warningartwork can represent a warning or a confirmed failure; pass the actual tone. comic-presentation.tsowns defaults and semantic tokens;Frame,RedX,rmBlock,ComicandHintComicapply the shared grammar. Scenes own only their cast, causal illustration and final pose.Tooltipowns interaction and placement. Do not duplicate these rules in each scene or page.- Keep the semantic kind and tone in all languages; localized text changes expression, not severity. Symbol-only controls retain accessible names.
- For each changed scene inspect its start, transition and settled pose in both themes, reduced motion and narrow layouts. Compare success, failure, limitation and neutral neighbours in the catalogue. Code-level tests do not establish visual clarity. Judge the actual tooltip size, not only an enlarged SVG. Improve staging, gaze and timing before enlarging figures or adding props and effects; remove additions that do not help the meaning or the gesture.
- Update this owner when accepting a new convention. Product documents link here instead of copying the palette, cast or animation table.
Interaction References
Radix colour roles separate surfaces, interaction states, borders and text instead of tinting every layer with the accent. Native text selection and pointer capture support held controls without disabling selection across the whole page.
Fluent tabs, switches and sliders distinguish content navigation, immediate binary settings and numeric adjustment. WAI-ARIA tabs defines the shared selection, focus and keyboard contract. GNOME popovers and utility panes distinguish brief contextual adjustments from tools alongside the main view. Piik's floating/detached tool choice applies that distinction to watching and remote input; Document Picture-in-Picture supplies the optional native window and its lifetime boundary.
Carbon status indicators supports combining semantic colour with shape and symbols; Carbon motion distinguishes functional feedback from occasional expressive movement.
Web Animations start time provides the native timeline alignment used by participant gestures.
Carbon tooltip guidance supports concise, contextual help where it adds information; required instructions stay visible beside the action. W3C hover/focus guidance supports panels remaining reachable for reading and being dismissible without moving the pointer away.
Carbon loading guidance supports avoiding competing indicators and keeping required user actions distinct from passive loading. Piik's selected waiting captions and fifteen-second cadence are its own presentation choice.