Praxis UI Product Design
Use this skill to make Praxis UI feel like a deliberate, contemporary enterprise product with a
recognizable point of view, not like a raw internal demo or an untouched component-library sample.
This is a visual product-direction and QA layer. Use it with the functional Praxis owner skill whenever semantics, contracts, persistence, dynamic-fields discovery, or editor correctness are also in scope.
Before changing this skill or judging a Praxis UI, inspect the current source for the involved
surface instead of relying on general design memory. For authoring and AI-assisted surfaces this
usually means the component, shell/editor layout, i18n catalogs, metadata/manifest/context pack,
diagnostics model, focused specs, and any official example or playground that materializes the same
workflow. The goal is to encode working Praxis product knowledge, not create a generic visual taste
guide.
Operating Modes
When composing existing widgets through Page Builder, read
composed-widget-design.md with the selected
component authoring skills. Its guidance applies to charts, collections, forms,
filters and editorial blocks, without prescribing a dashboard composition.
Choose the mode from the user's request before taking action:
- Audit/review mode: inspect, gather evidence, capture screenshots when feasible, and report prioritized findings. Do not edit files unless the user explicitly asks for fixes.
- Implementation mode: edit only when the request asks to create, redesign, polish, improve, fix, or apply changes.
If the request is ambiguous, default to audit/review mode for review wording and implementation mode for build/fix/polish wording.
Governance Preflight
Before editing in implementation mode, apply the active root, workspace, and subarea AGENTS.md files. Local AGENTS may narrow owner, validation, public artifacts, origins, and no-edit areas. If a Praxis Angular subarea lacks local AGENTS guidance, use praxis-angular-agents-governance before deriving validation or public artifact impact from memory.
Explicitly classify the change:
local-pequena
transversal
arquitetural
contrato-publico
docs-apenas
For transversal, arquitetural, or contrato-publico, produce the required short plan and impact map before editing:
- canonical subproject affected
- impacted consumers
- public docs potentially affected
- examples, playgrounds, or recipes potentially affected
- minimum tests or validations
- breaking-change risk
Visual/product design does not authorize new public contracts. If the UX need appears to require a new public token, input, output, event, service, config shape, public-api, ComponentDocMeta, AI manifest field, or metadata-driven field, first classify the fit as:
ja-suportado-so-ux
ja-suportado-mal-nomeado-ou-mal-materializado
suportado-parcialmente
lacuna-real-de-contrato
Only lacuna-real-de-contrato can justify a new contract, and it must follow the repository governance gates.
When the same work also uses Angular host or migration skills, align these UX classifications with the shared platform feedback vocabulary:
ja-suportado-so-ux -> already-supported: use the native Praxis path and fix only UX/presentation.
ja-suportado-mal-nomeado-ou-mal-materializado -> already-supported or supported-partially: consume the native primitive, then improve naming/materialization in the owner.
suportado-parcialmente -> supported-partially: keep the smallest temporary bridge and record the removal trigger.
lacuna-real-de-contrato -> platform-gap: open or register a traceable platform follow-up before adding public contract surface.
If a recurring visual workaround comes from weak migration guidance rather than a missing UI contract, classify it as migration-skill-gap and update the relevant codex-skills/ source.
Design System Stance
Treat visual quality as a platform concern. Before editing UI, identify the canonical owner of the visual or interaction problem:
- shared component or token in
@praxisui/core
- component library surface in
@praxisui/*
- authoring editor or settings-panel pattern
- host/demo-specific composition
- public example, recipe, or playground
Do not solve systemic UI problems with one-off CSS in a consumer. If the same issue would appear in multiple Praxis components, fix the shared primitive, token, component, or editor pattern.
Praxis UI must remain host-themeable. Use Angular Material theming tokens and Praxis design tokens/CSS custom properties as the first styling surface for color, typography, density, spacing, radius, elevation, focus, state, overlay, and surface contrast. Do not hardcode visual values in components, editors, examples, or hosts when a Material or Praxis token can express the intent. Host applications must be able to customize theme without patching internal component CSS.
When theming @praxisui/table from a host, prefer the component-owned --p-table-* CSS custom properties on the praxis-table host, such as header, row, border, paginator, and selection tokens. If the table component declares host-level defaults with higher specificity, override the same tokens on the concrete host state/class instead of styling MDC/Material internals or adding !important.
Use this owner decision matrix:
- affects 2+ libs, overlay layers, focus behavior, theme bridge, typography, spacing scale, color tokens, or shared surface contrast ->
@praxisui/core or the shared owner
- affects one configurable editor family -> the owning
@praxisui/* lib
- affects Settings Panel shell, footer actions, drawer sizing, or
SettingsValueProvider UX -> @praxisui/settings-panel
- affects only a demo/example with no reusable pattern -> host/demo
- affects config shape, persistence, apply/save/reset, runtime/editor parity, or public APIs -> load the functional owner skill before this visual layer
For controlType, aliases, optionSource, async-select, inline filters, dynamic-fields overlays, package-owned field tokens, or editorial discovery, use praxis-dynamic-fields-editorial as the primary skill and this skill only for visual QA.
Research-Informed Defaults
Apply the detailed rubrics in references/ when relevant. The non-negotiable defaults are: reuse shared components, preserve host theming through Material/Praxis tokens, choose controls by user intent rather than metadata shape, size fields by content and task importance, keep enterprise screens dense but scannable, validate visual changes with screenshots when feasible, and never trade accessibility or i18n for visual polish.
Distinctive Product Direction
Correctness, restraint, and token compliance are the quality floor, not the visual direction. When
the user asks for a modern, elegant, delightful, premium, distinctive, or redesigned experience,
load references/visual-direction-and-delight.md before proposing or implementing the UI.
Before code, establish a compact direction contract grounded in the actual product domain:
- actual operator and job to be done
- surface archetype and intended density
- visual thesis: mood, material, rhythm, and energy
- domain vocabulary, artifacts, and data shapes that can inform the composition
- one product-specific signature: spatial, informational, typographic, or interaction-based
- three generic defaults to reject and the deliberate replacements
- token and composition plan that remains host-themeable
- interaction thesis with only the motions that improve orientation, continuity, or feedback
Spend boldness in one place. An operational signature is not a marketing hero: it may be a highly
legible semantic decision trail, a distinctive list-detail rhythm, a diff-first preview, an
exceptionally fluent canvas-to-inspector transition, or another expression backed by the real
workflow and available contract. Keep surrounding chrome quiet enough for that signature to land.
Do not equate modern with a fashionable effect. Glass, gradients, oversized radius, floating cards,
purple accents, sparse layouts, and animation are not evidence of modernity. A modern enterprise UI
earns delight through spatial intelligence, immediate state legibility, direct manipulation,
continuity, fast scanning, excellent typography, and a coherent product-specific visual language.
Enterprise Authoring Workstation Baseline
Operational and editor screens must expose the working surface, not behave like a landing page. They fail if the first viewport is dominated by hero copy, decorative cards, large illustrations, decorative gradients, or explanatory marketing text instead of the actual task surface.
For Praxis authoring tools, make these visible when applicable:
- current selection: name, type, status, and incomplete/invalid state without opening a hidden panel
- global state: dirty, invalid, saving/applying, saved, readonly, permission-limited
- primary work region: editor/canvas/table/list/rule builder is visually dominant
- action priority: primary, secondary, destructive, and reset/cancel actions are distinct
- persistence feedback: apply/save/reset result is visible near the shell or active work area
- comparison: lists or trees support scanning and comparing related objects
- preview/result: available when round-trip confidence or runtime effect is material
- recovery: errors explain cause and next step without losing progress
First viewport heuristics:
- the primary work region is the largest meaningful region on desktop
- header, tabs, filters, helper text, and toolbar chrome do not dominate vertical space
- inspectors are secondary unless the task is pure property editing
- preview/result is not weaker than helper text when runtime confidence matters
- selected entity summary remains visible in long inspectors or detail panes
Semantic Decision UX
Praxis is a platform for AI-authored semantic decisions. Product UX must therefore materialize the
decision chain, not hide it behind decorative "AI" chrome.
For assistant, authoring, governance, Domain Catalog, Page Builder, and metadata-driven experiences,
make these human-reviewable when the contract provides them:
- resolved intent, scope, and selected target
- canonical decision or proposed materialization
- evidence, grounding, or context source used by the decision
- diagnostics, ambiguity, unsupported capability, or policy limitation
- preview/result before irreversible apply/save when runtime confidence matters
- next safe action, including clarification, review, apply, save, or rollback
Do not turn semantic evidence into local explanatory cards that drift from the contract. If the
backend/runtime publishes diagnostics, authoringContract, consultativeContext, quick replies,
component edit plans, Domain Catalog references, or decision diagnostics, the UI should surface those
facts with hierarchy and product language. If those facts do not exist, classify the gap before
inventing frontend-only state.
Visual polish must never make a fabricated patch, keyword-routed intent, unsupported capability, or
JSON-only workaround look canonical. Use visual hierarchy to expose uncertainty and governance, not
to smooth it over.
Praxis Visual Doctrine
Praxis UI should feel:
- precise, operational, and trustworthy
- compact without being cramped
- visually quiet until state or action requires emphasis
- recognizably Praxis and specific to the workflow rather than generically "Material"
- crafted in typography, rhythm, state transitions, and micro-interaction
- metadata-driven but understandable to a human author
- consistent across runtime, authoring, examples, and docs
Avoid:
- nested cards or framed panels without a real information-architecture purpose
- using borders as the primary layout mechanism
- one-off color literals, spacing values, shadows, radii, or typography
- Material/Praxis-token bypasses that prevent host theme customization
- decorative gradients or oversized empty marketing composition in operational tools
- dark-theme surfaces where labels, values, helper text, and borders have similar weight
- local copies of controls that should come from a shared Praxis component
Preflight
Before editing, answer:
- What is the primary user workflow?
- What is the primary action and what is secondary?
- Which shared Praxis component, token, or editor pattern owns the issue?
- Is the problem layout architecture, component design, state design, copy, accessibility, or visual polish?
- Which surface type is this: authoring tool, runtime component, playground/example, or public docs?
- Are any fields visual choices that should use icons, swatches, segmented controls, sliders, or toggles instead of a generic select?
- Are commands, modes, filters, navigation, and destructive actions represented by distinct UI primitives?
- Does the grid distribution match control importance, content length, and grouping, or are there orphan controls/empty columns?
- Which desktop and narrow/mobile viewport must be checked?
- Which public examples, playgrounds, recipes, or docs mirror this UI?
- What is the visual thesis for this workflow, in one concrete sentence?
- What single signature makes the result specific to this product and task?
- Which three generic visual or structural defaults will be rejected?
- What calibrated levels of distinction, motion, and density fit this operator?
If the task affects config shape, persistence, apply/save/reset, dynamic fields discovery, or public component contracts, load the corresponding Praxis canonical skill before editing.
Surface Matrix
Use the surface type to tune the work:
- Authoring tools: optimize selection, editing, preview/result, dirty/invalid state, persistence, permissions, keyboard flow, and recovery.
- Runtime components: optimize clarity of use, accessibility, tokens, states, responsive behavior, and host integration.
- Playgrounds/examples: optimize demonstrability, realistic controls, minimal explanatory copy, reproducible states, and links back to docs/contracts without redefining them.
- Public docs: optimize explanation, examples, screenshots, and reproducibility; never redefine backend/runtime contracts alone.
Audit Workflow
Use this workflow when the user asks to review, analyze, critique, inspect, or assess:
- Inspect the existing UI implementation, applicable AGENTS files, nearby patterns, and available screenshots.
- Load
references/praxis-visual-rubric.md; load other references only as their conditions apply.
- Gather static evidence with focused probes when useful:
- raw visual literals:
rg "#[0-9a-fA-F]{3,8}|rgb\\(|hsl\\(" <scope>
- style bypasses:
rg "::ng-deep|!important|box-shadow|border-radius|z-index" <scope>
- token usage:
rg "--pdx-|--praxis-|mat-|Material|token" <scope>
- overlay risks:
rg "Overlay|cdk-overlay|mat-select|mat-menu|mat-dialog|mat-autocomplete" <scope>
- i18n paths:
rg "PraxisI18nService|i18n|pt-BR|en-US" <scope>
- public surfaces:
rg "public-api|@Input|@Output|InjectionToken|ComponentDocMeta" <scope>
- Classify findings by hierarchy, information architecture, layout, component choice, interaction primitive choice, spacing/density, spatial composition, product specificity, signature strength, aesthetic coherence, state design, accessibility, responsive behavior, theme/tokens, and i18n.
- Report prioritized findings with file/screenshot evidence and recommend the canonical owner. Do not edit.
Implementation Workflow
Use this workflow when the user asks to create, redesign, polish, improve, fix, or apply changes:
- Inspect the implementation, applicable AGENTS files, nearby patterns, and functional owner skill.
- Run the Governance Preflight and impact map when required.
- Load required references for the affected visual dimension.
- Run the quick design-system audit: reused components, Material tokens, Praxis tokens/custom properties, raw values, host-themeability, local duplicate controls, missing primitive/owner, i18n path, and overlay behavior.
- For modern, delightful, distinctive, premium, or redesign work, write the direction contract from
references/visual-direction-and-delight.md and reject generic defaults before coding.
- Classify the UX problem and decide whether the fix belongs in a shared Praxis primitive, owning lib, settings-panel shell, or local host/demo.
- Implement the smallest canonical platform fix that satisfies repository governance and the chosen direction.
- Run the smallest relevant build/test for the changed package.
- Open the UI only through official scripts, routes, ports, and origins. Do not invent local servers or origins.
- Capture desktop plus narrow/mobile screenshots when feasible, including open overlay states when relevant. When the workflow opens a Settings Panel, metadata editor, drawer, side sheet, or inspector, include at least one screenshot with that editor open in the narrow viewport; runtime-only narrow screenshots can miss clipped editor copy, hidden controls, and broken authoring access.
- Inspect screenshots against the rubrics. Run the genericity, swap, squint, signature, coherence, and craft tests from the direction reference, then iterate on the top visual defects before reporting completion.
If browser validation is not feasible, state exactly why and perform static review against the rubrics.
Authoring Editor Patterns
For detailed authoring editor guidance, load references/authoring-editor-patterns.md. Core rules:
- keep navigation, selection, editing, preview, and persistence roles visually distinct
- make the primary canvas/editor/list/rule builder visually dominant
- use guided builders for rules, actions, conditions, and effects
- use icon or icon+text segmented controls for standard visual options
- group rows by task and size fields by expected content and importance
Avoid:
- property dumps, arbitrary equal-column grids, generic text selects for visual options, clipped overlays, stranded compact controls, and card grids as the default editor layout
Executive Showcase & Fine-Detail Craftsmanship Rules
Whenever creating or modifying any component, resource page, KPI band, compact filter, micro-visualization, or 360° analytical drawer in a Praxis showcase or host — no matter how small the change — enforce these fine-detail geometry and runtime rules:
- KPI Band & Card Accent Geometry (No "Crescent Moon" Border Defect): Never apply a thick
border-left: 4px solid directly to a card with border-radius: 12px+. Render the semantic accent bar as an inset vertical strip via ::before (left: 0; top: 10px; bottom: 10px; width: 3px; border-radius: 0 3px 3px 0). Every card in a KPI band must render a consistent 34×34px icon badge, support all semantic [data-tone] variants (primary, accent, info, success, warning, danger, neutral, ready, destructive), and toggle its filter off (aria-pressed="false") when clicked a second time.
- Micro-Visualizations in Cards vs. Table Cells: On
surface: 'card-summary' where the primary KPI number is already displayed in the card header, configure bullet micro-visualizations with compactValue: false (showing only Meta: X% without duplicating the primary metric) and radial micro-visualizations with size: 'sm' (38px). On surface: 'table-cell', verify in the DOM that .pfx-micro-bullet__actual or .pfx-micro-radial renders the visual graphic rather than falling back to plain text due to invalid valueExpr/targetExpr paths or unsupported JS operators (??).
- Compact Filter Bar Icon Hygiene: In compact inline filter selects (
pdx-FilterSelect), render the expand_more chevron only in the resting state (:not(.is-active):not(.pdx-has-quick-clear)). Hide the chevron whenever a value is selected so it never collides with the quick-clear (×) button.
- Analytical 360° Drawer Safe Expressions: In
SafeExpressionEvaluator, || is a boolean operator (true/false). Any titleExpr, subtitleExpr, or valueExpr fallback in PraxisAnalyticalDrawerSchema must use coalesce(row.fieldA, row.fieldB, '-'), never ||.
- Frameless Child Surfaces (No Double Padding): When
<praxis-resource-page> or a workbench is hosted inside .praxis-shell__content, keep the child host padding: 0 so outer shell padding is never duplicated and vertical rhythm (16px gap between KPI band, filter bar, and table) remains uniform across all routes.
Must-Fail Checks
A Praxis UI change is incomplete if any of these are true:
- the main task is not visually obvious within a few seconds
- the primary action is not clearly prioritized
- a request for modern, delightful, premium, or distinctive UI ends in an untouched Material look, generic sidebar-plus-card composition, or a surface with no defensible product-specific signature
- the chosen visual thesis is not visible in typography, composition, state treatment, or interaction
- a common visual option is represented by a generic text select when a familiar icon/segmented control would be clearer
- a compact field is stretched or stranded in a wide empty row without a layout reason
- text is clipped, overlapped, hidden, or too low contrast
- popovers, dropdowns, tooltips, dialogs, drawers, or overlays are clipped
- narrow/mobile authoring depends on a global toolbar control that is hidden at that breakpoint and the validated workflow has no equivalent accessible entrypoint
- keyboard focus is invisible or the primary keyboard task path is broken
- mobile or narrow layout requires horizontal scrolling for ordinary use
- the implementation bypasses shared Praxis tokens or components without justification
- styling bypasses Material/Praxis tokens and would require host CSS patching to theme
- new internal lib/editor copy is hardcoded instead of using the applicable Praxis i18n path
- CSS custom properties or tokens are introduced as public theming surface without public-contract governance
- a rounded card uses a direct thick
border-left that warps corners, a compact filter chevron collides with the quick-clear (×) button, a KPI card duplicates its primary metric inside a card-summary bullet, or a 360° drawer displays "true" from an unguarded || expression
Load references/praxis-visual-rubric.md for the full rubric.
Validation Evidence
Separate visual evidence from contract evidence:
- Visual evidence: route, official origin/port, viewport sizes, states captured, screenshot/browser tool used, defects fixed, defects deferred.
- Contract evidence: build/test/spec/e2e required by the changed package, public API, config shape, manifest, or AGENTS guidance.
Screenshot evidence never replaces required contract validation.
Widget Material And Preset Review
For shell preset identity, glass/opaque treatments, border experiments or real-widget
comparisons, read widget-shell-material-review.md.
Audit the Core catalog, resolved context, explicit appearance and the actual child component
before proposing more presets. A thumbnail or passing name/ID test does not prove visual identity.
References
Load only what is needed, but follow these mandatory routing rules:
references/research-curation.md for the external design-system and UX principles behind this skill.
- Load
references/visual-direction-and-delight.md for new visual directions, redesigns, or requests using modern, delightful, elegant, premium, distinctive, memorable, polished, or non-generic language.
- Load
references/praxis-visual-rubric.md in audit mode and before screenshot review.
- Load
references/authoring-editor-patterns.md for settings panels, builders, schema editors, rule editors, metadata-driven authoring, field layout, or workstation composition.
- Load
references/interaction-control-selection.md when replacing or choosing selects, buttons, fields, commands, choices, modes, filters, visual properties, destructive actions, preview, or bulk operations.
- Load
references/theme-accessibility-i18n-gate.md when changing CSS, tokens, theme surfaces, overlays, icon-heavy controls, labels, tooltips, aria text, or internal editor copy.
- Load
references/screenshot-review-checklist.md before finalizing visual UI work.
1---2name: praxis-ui-product-design3description: "Use alongside the canonical functional Praxis skill when the user's request materially asks for visual/product UX quality in Praxis web UI: art direction, distinctive product character, modern or delightful composition, auditing, redesigning, polishing, screenshot QA, visual hierarchy, responsive behavior, dark theme quality, or accessibility of visual controls in Angular UI, authoring editors, settings panels, dynamic form/table/list experiences, playgrounds, or examples. Do not use as the primary skill for config round-trip, persistence, public APIs, dynamic-fields discovery, metadata contracts, or ordinary editor correctness unless visual UX is explicitly in scope."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-ui-product-design6---78# Praxis UI Product Design910Use this skill to make Praxis UI feel like a deliberate, contemporary enterprise product with a11recognizable point of view, not like a raw internal demo or an untouched component-library sample.1213This is a visual product-direction and QA layer. Use it with the functional Praxis owner skill whenever semantics, contracts, persistence, dynamic-fields discovery, or editor correctness are also in scope.1415Before changing this skill or judging a Praxis UI, inspect the current source for the involved16surface instead of relying on general design memory. For authoring and AI-assisted surfaces this17usually means the component, shell/editor layout, i18n catalogs, metadata/manifest/context pack,18diagnostics model, focused specs, and any official example or playground that materializes the same19workflow. The goal is to encode working Praxis product knowledge, not create a generic visual taste20guide.2122## Operating Modes2324When composing existing widgets through Page Builder, read25[composed-widget-design.md](references/composed-widget-design.md) with the selected26component authoring skills. Its guidance applies to charts, collections, forms,27filters and editorial blocks, without prescribing a dashboard composition.2829Choose the mode from the user's request before taking action:3031- Audit/review mode: inspect, gather evidence, capture screenshots when feasible, and report prioritized findings. Do not edit files unless the user explicitly asks for fixes.32- Implementation mode: edit only when the request asks to create, redesign, polish, improve, fix, or apply changes.3334If the request is ambiguous, default to audit/review mode for review wording and implementation mode for build/fix/polish wording.3536## Governance Preflight3738Before editing in implementation mode, apply the active root, workspace, and subarea `AGENTS.md` files. Local AGENTS may narrow owner, validation, public artifacts, origins, and no-edit areas. If a Praxis Angular subarea lacks local AGENTS guidance, use `praxis-angular-agents-governance` before deriving validation or public artifact impact from memory.3940Explicitly classify the change:4142- `local-pequena`43- `transversal`44- `arquitetural`45- `contrato-publico`46- `docs-apenas`4748For `transversal`, `arquitetural`, or `contrato-publico`, produce the required short plan and impact map before editing:4950- canonical subproject affected51- impacted consumers52- public docs potentially affected53- examples, playgrounds, or recipes potentially affected54- minimum tests or validations55- breaking-change risk5657Visual/product design does not authorize new public contracts. If the UX need appears to require a new public token, input, output, event, service, config shape, `public-api`, `ComponentDocMeta`, AI manifest field, or metadata-driven field, first classify the fit as:5859- `ja-suportado-so-ux`60- `ja-suportado-mal-nomeado-ou-mal-materializado`61- `suportado-parcialmente`62- `lacuna-real-de-contrato`6364Only `lacuna-real-de-contrato` can justify a new contract, and it must follow the repository governance gates.6566When the same work also uses Angular host or migration skills, align these UX classifications with the shared platform feedback vocabulary:6768- `ja-suportado-so-ux` -> `already-supported`: use the native Praxis path and fix only UX/presentation.69- `ja-suportado-mal-nomeado-ou-mal-materializado` -> `already-supported` or `supported-partially`: consume the native primitive, then improve naming/materialization in the owner.70- `suportado-parcialmente` -> `supported-partially`: keep the smallest temporary bridge and record the removal trigger.71- `lacuna-real-de-contrato` -> `platform-gap`: open or register a traceable platform follow-up before adding public contract surface.7273If a recurring visual workaround comes from weak migration guidance rather than a missing UI contract, classify it as `migration-skill-gap` and update the relevant `codex-skills/` source.7475## Design System Stance7677Treat visual quality as a platform concern. Before editing UI, identify the canonical owner of the visual or interaction problem:7879- shared component or token in `@praxisui/core`80- component library surface in `@praxisui/*`81- authoring editor or settings-panel pattern82- host/demo-specific composition83- public example, recipe, or playground8485Do not solve systemic UI problems with one-off CSS in a consumer. If the same issue would appear in multiple Praxis components, fix the shared primitive, token, component, or editor pattern.8687Praxis UI must remain host-themeable. Use Angular Material theming tokens and Praxis design tokens/CSS custom properties as the first styling surface for color, typography, density, spacing, radius, elevation, focus, state, overlay, and surface contrast. Do not hardcode visual values in components, editors, examples, or hosts when a Material or Praxis token can express the intent. Host applications must be able to customize theme without patching internal component CSS.8889When theming `@praxisui/table` from a host, prefer the component-owned `--p-table-*` CSS custom properties on the `praxis-table` host, such as header, row, border, paginator, and selection tokens. If the table component declares host-level defaults with higher specificity, override the same tokens on the concrete host state/class instead of styling MDC/Material internals or adding `!important`.9091Use this owner decision matrix:9293- affects 2+ libs, overlay layers, focus behavior, theme bridge, typography, spacing scale, color tokens, or shared surface contrast -> `@praxisui/core` or the shared owner94- affects one configurable editor family -> the owning `@praxisui/*` lib95- affects Settings Panel shell, footer actions, drawer sizing, or `SettingsValueProvider` UX -> `@praxisui/settings-panel`96- affects only a demo/example with no reusable pattern -> host/demo97- affects config shape, persistence, apply/save/reset, runtime/editor parity, or public APIs -> load the functional owner skill before this visual layer9899For `controlType`, aliases, `optionSource`, `async-select`, inline filters, dynamic-fields overlays, package-owned field tokens, or editorial discovery, use `praxis-dynamic-fields-editorial` as the primary skill and this skill only for visual QA.100101## Research-Informed Defaults102103Apply the detailed rubrics in `references/` when relevant. The non-negotiable defaults are: reuse shared components, preserve host theming through Material/Praxis tokens, choose controls by user intent rather than metadata shape, size fields by content and task importance, keep enterprise screens dense but scannable, validate visual changes with screenshots when feasible, and never trade accessibility or i18n for visual polish.104105## Distinctive Product Direction106107Correctness, restraint, and token compliance are the quality floor, not the visual direction. When108the user asks for a modern, elegant, delightful, premium, distinctive, or redesigned experience,109load `references/visual-direction-and-delight.md` before proposing or implementing the UI.110111Before code, establish a compact direction contract grounded in the actual product domain:112113- actual operator and job to be done114- surface archetype and intended density115- visual thesis: mood, material, rhythm, and energy116- domain vocabulary, artifacts, and data shapes that can inform the composition117- one product-specific signature: spatial, informational, typographic, or interaction-based118- three generic defaults to reject and the deliberate replacements119- token and composition plan that remains host-themeable120- interaction thesis with only the motions that improve orientation, continuity, or feedback121122Spend boldness in one place. An operational signature is not a marketing hero: it may be a highly123legible semantic decision trail, a distinctive list-detail rhythm, a diff-first preview, an124exceptionally fluent canvas-to-inspector transition, or another expression backed by the real125workflow and available contract. Keep surrounding chrome quiet enough for that signature to land.126127Do not equate modern with a fashionable effect. Glass, gradients, oversized radius, floating cards,128purple accents, sparse layouts, and animation are not evidence of modernity. A modern enterprise UI129earns delight through spatial intelligence, immediate state legibility, direct manipulation,130continuity, fast scanning, excellent typography, and a coherent product-specific visual language.131132## Enterprise Authoring Workstation Baseline133134Operational and editor screens must expose the working surface, not behave like a landing page. They fail if the first viewport is dominated by hero copy, decorative cards, large illustrations, decorative gradients, or explanatory marketing text instead of the actual task surface.135136For Praxis authoring tools, make these visible when applicable:137138- current selection: name, type, status, and incomplete/invalid state without opening a hidden panel139- global state: dirty, invalid, saving/applying, saved, readonly, permission-limited140- primary work region: editor/canvas/table/list/rule builder is visually dominant141- action priority: primary, secondary, destructive, and reset/cancel actions are distinct142- persistence feedback: apply/save/reset result is visible near the shell or active work area143- comparison: lists or trees support scanning and comparing related objects144- preview/result: available when round-trip confidence or runtime effect is material145- recovery: errors explain cause and next step without losing progress146147First viewport heuristics:148149- the primary work region is the largest meaningful region on desktop150- header, tabs, filters, helper text, and toolbar chrome do not dominate vertical space151- inspectors are secondary unless the task is pure property editing152- preview/result is not weaker than helper text when runtime confidence matters153- selected entity summary remains visible in long inspectors or detail panes154155## Semantic Decision UX156157Praxis is a platform for AI-authored semantic decisions. Product UX must therefore materialize the158decision chain, not hide it behind decorative "AI" chrome.159160For assistant, authoring, governance, Domain Catalog, Page Builder, and metadata-driven experiences,161make these human-reviewable when the contract provides them:162163- resolved intent, scope, and selected target164- canonical decision or proposed materialization165- evidence, grounding, or context source used by the decision166- diagnostics, ambiguity, unsupported capability, or policy limitation167- preview/result before irreversible apply/save when runtime confidence matters168- next safe action, including clarification, review, apply, save, or rollback169170Do not turn semantic evidence into local explanatory cards that drift from the contract. If the171backend/runtime publishes diagnostics, `authoringContract`, `consultativeContext`, quick replies,172component edit plans, Domain Catalog references, or decision diagnostics, the UI should surface those173facts with hierarchy and product language. If those facts do not exist, classify the gap before174inventing frontend-only state.175176Visual polish must never make a fabricated patch, keyword-routed intent, unsupported capability, or177JSON-only workaround look canonical. Use visual hierarchy to expose uncertainty and governance, not178to smooth it over.179180## Praxis Visual Doctrine181182Praxis UI should feel:183184- precise, operational, and trustworthy185- compact without being cramped186- visually quiet until state or action requires emphasis187- recognizably Praxis and specific to the workflow rather than generically "Material"188- crafted in typography, rhythm, state transitions, and micro-interaction189- metadata-driven but understandable to a human author190- consistent across runtime, authoring, examples, and docs191192Avoid:193194- nested cards or framed panels without a real information-architecture purpose195- using borders as the primary layout mechanism196- one-off color literals, spacing values, shadows, radii, or typography197- Material/Praxis-token bypasses that prevent host theme customization198- decorative gradients or oversized empty marketing composition in operational tools199- dark-theme surfaces where labels, values, helper text, and borders have similar weight200- local copies of controls that should come from a shared Praxis component201202## Preflight203204Before editing, answer:2052061. What is the primary user workflow?2072. What is the primary action and what is secondary?2083. Which shared Praxis component, token, or editor pattern owns the issue?2094. Is the problem layout architecture, component design, state design, copy, accessibility, or visual polish?2105. Which surface type is this: authoring tool, runtime component, playground/example, or public docs?2116. Are any fields visual choices that should use icons, swatches, segmented controls, sliders, or toggles instead of a generic select?2127. Are commands, modes, filters, navigation, and destructive actions represented by distinct UI primitives?2138. Does the grid distribution match control importance, content length, and grouping, or are there orphan controls/empty columns?2149. Which desktop and narrow/mobile viewport must be checked?21510. Which public examples, playgrounds, recipes, or docs mirror this UI?21611. What is the visual thesis for this workflow, in one concrete sentence?21712. What single signature makes the result specific to this product and task?21813. Which three generic visual or structural defaults will be rejected?21914. What calibrated levels of distinction, motion, and density fit this operator?220221If the task affects config shape, persistence, apply/save/reset, dynamic fields discovery, or public component contracts, load the corresponding Praxis canonical skill before editing.222223## Surface Matrix224225Use the surface type to tune the work:226227- Authoring tools: optimize selection, editing, preview/result, dirty/invalid state, persistence, permissions, keyboard flow, and recovery.228- Runtime components: optimize clarity of use, accessibility, tokens, states, responsive behavior, and host integration.229- Playgrounds/examples: optimize demonstrability, realistic controls, minimal explanatory copy, reproducible states, and links back to docs/contracts without redefining them.230- Public docs: optimize explanation, examples, screenshots, and reproducibility; never redefine backend/runtime contracts alone.231232## Audit Workflow233234Use this workflow when the user asks to review, analyze, critique, inspect, or assess:2352361. Inspect the existing UI implementation, applicable AGENTS files, nearby patterns, and available screenshots.2372. Load `references/praxis-visual-rubric.md`; load other references only as their conditions apply.2383. Gather static evidence with focused probes when useful:239 - raw visual literals: `rg "#[0-9a-fA-F]{3,8}|rgb\\(|hsl\\(" <scope>`240 - style bypasses: `rg "::ng-deep|!important|box-shadow|border-radius|z-index" <scope>`241 - token usage: `rg "--pdx-|--praxis-|mat-|Material|token" <scope>`242 - overlay risks: `rg "Overlay|cdk-overlay|mat-select|mat-menu|mat-dialog|mat-autocomplete" <scope>`243 - i18n paths: `rg "PraxisI18nService|i18n|pt-BR|en-US" <scope>`244 - public surfaces: `rg "public-api|@Input|@Output|InjectionToken|ComponentDocMeta" <scope>`2454. Classify findings by hierarchy, information architecture, layout, component choice, interaction primitive choice, spacing/density, spatial composition, product specificity, signature strength, aesthetic coherence, state design, accessibility, responsive behavior, theme/tokens, and i18n.2465. Report prioritized findings with file/screenshot evidence and recommend the canonical owner. Do not edit.247248## Implementation Workflow249250Use this workflow when the user asks to create, redesign, polish, improve, fix, or apply changes:2512521. Inspect the implementation, applicable AGENTS files, nearby patterns, and functional owner skill.2532. Run the Governance Preflight and impact map when required.2543. Load required references for the affected visual dimension.2554. Run the quick design-system audit: reused components, Material tokens, Praxis tokens/custom properties, raw values, host-themeability, local duplicate controls, missing primitive/owner, i18n path, and overlay behavior.2565. For modern, delightful, distinctive, premium, or redesign work, write the direction contract from `references/visual-direction-and-delight.md` and reject generic defaults before coding.2576. Classify the UX problem and decide whether the fix belongs in a shared Praxis primitive, owning lib, settings-panel shell, or local host/demo.2587. Implement the smallest canonical platform fix that satisfies repository governance and the chosen direction.2598. Run the smallest relevant build/test for the changed package.2609. Open the UI only through official scripts, routes, ports, and origins. Do not invent local servers or origins.26110. Capture desktop plus narrow/mobile screenshots when feasible, including open overlay states when relevant. When the workflow opens a Settings Panel, metadata editor, drawer, side sheet, or inspector, include at least one screenshot with that editor open in the narrow viewport; runtime-only narrow screenshots can miss clipped editor copy, hidden controls, and broken authoring access.26211. Inspect screenshots against the rubrics. Run the genericity, swap, squint, signature, coherence, and craft tests from the direction reference, then iterate on the top visual defects before reporting completion.263264If browser validation is not feasible, state exactly why and perform static review against the rubrics.265266## Authoring Editor Patterns267268For detailed authoring editor guidance, load `references/authoring-editor-patterns.md`. Core rules:269270- keep navigation, selection, editing, preview, and persistence roles visually distinct271- make the primary canvas/editor/list/rule builder visually dominant272- use guided builders for rules, actions, conditions, and effects273- use icon or icon+text segmented controls for standard visual options274- group rows by task and size fields by expected content and importance275276Avoid:277278- property dumps, arbitrary equal-column grids, generic text selects for visual options, clipped overlays, stranded compact controls, and card grids as the default editor layout279280## Executive Showcase & Fine-Detail Craftsmanship Rules281282Whenever creating or modifying any component, resource page, KPI band, compact filter, micro-visualization, or 360° analytical drawer in a Praxis showcase or host — no matter how small the change — enforce these fine-detail geometry and runtime rules:283284- **KPI Band & Card Accent Geometry (No "Crescent Moon" Border Defect):** Never apply a thick `border-left: 4px solid` directly to a card with `border-radius: 12px+`. Render the semantic accent bar as an inset vertical strip via `::before` (`left: 0; top: 10px; bottom: 10px; width: 3px; border-radius: 0 3px 3px 0`). Every card in a KPI band must render a consistent `34×34px` icon badge, support all semantic `[data-tone]` variants (`primary`, `accent`, `info`, `success`, `warning`, `danger`, `neutral`, `ready`, `destructive`), and toggle its filter off (`aria-pressed="false"`) when clicked a second time.285- **Micro-Visualizations in Cards vs. Table Cells:** On `surface: 'card-summary'` where the primary KPI number is already displayed in the card header, configure `bullet` micro-visualizations with `compactValue: false` (showing only `Meta: X%` without duplicating the primary metric) and `radial` micro-visualizations with `size: 'sm'` (`38px`). On `surface: 'table-cell'`, verify in the DOM that `.pfx-micro-bullet__actual` or `.pfx-micro-radial` renders the visual graphic rather than falling back to plain text due to invalid `valueExpr`/`targetExpr` paths or unsupported JS operators (`??`).286- **Compact Filter Bar Icon Hygiene:** In compact inline filter selects (`pdx-FilterSelect`), render the `expand_more` chevron only in the resting state (`:not(.is-active):not(.pdx-has-quick-clear)`). Hide the chevron whenever a value is selected so it never collides with the quick-clear (`×`) button.287- **Analytical 360° Drawer Safe Expressions:** In `SafeExpressionEvaluator`, `||` is a boolean operator (`true`/`false`). Any `titleExpr`, `subtitleExpr`, or `valueExpr` fallback in `PraxisAnalyticalDrawerSchema` must use `coalesce(row.fieldA, row.fieldB, '-')`, never `||`.288- **Frameless Child Surfaces (No Double Padding):** When `<praxis-resource-page>` or a workbench is hosted inside `.praxis-shell__content`, keep the child host `padding: 0` so outer shell padding is never duplicated and vertical rhythm (`16px` gap between KPI band, filter bar, and table) remains uniform across all routes.289290## Must-Fail Checks291292A Praxis UI change is incomplete if any of these are true:293294- the main task is not visually obvious within a few seconds295- the primary action is not clearly prioritized296- a request for modern, delightful, premium, or distinctive UI ends in an untouched Material look, generic sidebar-plus-card composition, or a surface with no defensible product-specific signature297- the chosen visual thesis is not visible in typography, composition, state treatment, or interaction298- a common visual option is represented by a generic text select when a familiar icon/segmented control would be clearer299- a compact field is stretched or stranded in a wide empty row without a layout reason300- text is clipped, overlapped, hidden, or too low contrast301- popovers, dropdowns, tooltips, dialogs, drawers, or overlays are clipped302- narrow/mobile authoring depends on a global toolbar control that is hidden at that breakpoint and the validated workflow has no equivalent accessible entrypoint303- keyboard focus is invisible or the primary keyboard task path is broken304- mobile or narrow layout requires horizontal scrolling for ordinary use305- the implementation bypasses shared Praxis tokens or components without justification306- styling bypasses Material/Praxis tokens and would require host CSS patching to theme307- new internal lib/editor copy is hardcoded instead of using the applicable Praxis i18n path308- CSS custom properties or tokens are introduced as public theming surface without public-contract governance309- a rounded card uses a direct thick `border-left` that warps corners, a compact filter chevron collides with the quick-clear (`×`) button, a KPI card duplicates its primary metric inside a `card-summary` bullet, or a 360° drawer displays `"true"` from an unguarded `||` expression310311Load `references/praxis-visual-rubric.md` for the full rubric.312313## Validation Evidence314315Separate visual evidence from contract evidence:316317- Visual evidence: route, official origin/port, viewport sizes, states captured, screenshot/browser tool used, defects fixed, defects deferred.318- Contract evidence: build/test/spec/e2e required by the changed package, public API, config shape, manifest, or AGENTS guidance.319320Screenshot evidence never replaces required contract validation.321322## Widget Material And Preset Review323324For shell preset identity, glass/opaque treatments, border experiments or real-widget325comparisons, read [widget-shell-material-review.md](references/widget-shell-material-review.md).326Audit the Core catalog, resolved context, explicit appearance and the actual child component327before proposing more presets. A thumbnail or passing name/ID test does not prove visual identity.328329## References330331Load only what is needed, but follow these mandatory routing rules:332333- `references/research-curation.md` for the external design-system and UX principles behind this skill.334- Load `references/visual-direction-and-delight.md` for new visual directions, redesigns, or requests using modern, delightful, elegant, premium, distinctive, memorable, polished, or non-generic language.335- Load `references/praxis-visual-rubric.md` in audit mode and before screenshot review.336- Load `references/authoring-editor-patterns.md` for settings panels, builders, schema editors, rule editors, metadata-driven authoring, field layout, or workstation composition.337- Load `references/interaction-control-selection.md` when replacing or choosing selects, buttons, fields, commands, choices, modes, filters, visual properties, destructive actions, preview, or bulk operations.338- Load `references/theme-accessibility-i18n-gate.md` when changing CSS, tokens, theme surfaces, overlays, icon-heavy controls, labels, tooltips, aria text, or internal editor copy.339- Load `references/screenshot-review-checklist.md` before finalizing visual UI work.340