Files

T

Claudio Ortolina f92a41241f Improve ui-framework skill with project conventions

Add project-specific UI checklist, component organization,
LiveView structure, toast patterns, and routing conventions
above the usage-rules managed section. Widen trigger description.

2026-04-09 16:24:35 +01:00

5.0 KiB

Raw Blame History

name, description, metadata

name

description

metadata

ui-framework

Use this skill when working with LiveViews, UI components using the Phoenix framework, and in general ANY FILE THAT CONTAINS HTML. Use proactively when editing .heex files, LiveView modules, LiveComponents, or any component module under lib/music_library_web/components/.

managed-by
usage-rules

Project UI Conventions

Before writing or modifying UI code, follow these project-specific rules. They take precedence over the generic reference material below.

Checklist

Gettext all user-facing strings. Every string visible to users must be wrapped in gettext/1 or pgettext/2. After adding new strings, run mix gettext.extract --merge to update .pot/.po files.
Dark mode always paired. Every color class needs its dark variant: text-zinc-900 dark:text-zinc-100, bg-zinc-50 dark:bg-zinc-800, etc.
Wishlisted items get dimmed styling: opacity-60 hover:opacity-100 transition-opacity.
Icons inside buttons use the icon class — not explicit size classes like h-5 w-5 or size-3.5. Fluxon auto-sizes icons based on the button's size prop.
Artist names use joinphrase from MusicBrainz — never join artist names with a literal ", ".
Streams for all collections. Use LiveView streams, not list assigns. See the LiveView reference below for stream patterns.

Component organization

Generic UI → CoreComponents
Record-specific → RecordComponents
Scrobble-specific → ScrobbleComponents
Search-specific → SearchComponents
Stats-specific → StatsComponents, ChartComponents
Extract a function component when identical markup appears in 3+ places.

LiveView structure

mount/3 sets @current_section
handle_params/3 loads data and sets @page_title (via pattern-matched private page_title/2)
handle_info/2 receives LiveComponent messages
LiveComponents communicate with parent via send(self(), {__MODULE__, msg})

Toast notifications

In LiveViews: put_toast(socket, :info, "message") (arity 3)
In LiveComponents: put_toast!(:info, "message") (arity 2)
User-facing error reasons go through ErrorMessages.friendly_message/1 — never inspect(reason)

Routes

Three routes per resource with show modals: :show, :edit (at /show/edit), :add_*
Modals close via JS.patch back to the base route
Search state in URL query params via push_patch
Conditional links: purchased_at determines /collection/ vs /wishlist/ paths

Fluxon components

Read references/fluxon.md when you need to use a specific Fluxon component — it contains the full attribute/slot API for each component. You can also search with:

mix usage_rules.search_docs "component_name" -p fluxon

Additional References

Searching Documentation

mix usage_rules.search_docs "search term" -p phoenix -p phoenix_ecto -p phoenix_html -p phoenix_live_dashboard -p phoenix_live_reload -p phoenix_live_view -p fluxon

Available Mix Tasks

mix compile.phoenix
mix phx - Prints Phoenix help information
mix phx.digest - Digests and compresses static files
mix phx.digest.clean - Removes old versions of static assets.
mix phx.gen - Lists all available Phoenix generators
mix phx.gen.auth - Generates authentication logic for a resource
mix phx.gen.auth.hashing_library
mix phx.gen.auth.injector
mix phx.gen.auth.migration
mix phx.gen.cert - Generates a self-signed certificate for HTTPS testing
mix phx.gen.channel - Generates a Phoenix channel
mix phx.gen.context - Generates a context with functions around an Ecto schema
mix phx.gen.embedded - Generates an embedded Ecto schema file
mix phx.gen.html - Generates context and controller for an HTML resource
mix phx.gen.json - Generates context and controller for a JSON resource
mix phx.gen.live - Generates LiveView, templates, and context for a resource
mix phx.gen.notifier - Generates a notifier that delivers emails by default
mix phx.gen.presence - Generates a Presence tracker
mix phx.gen.release - Generates release files and optional Dockerfile for release-based deployments
mix phx.gen.schema - Generates an Ecto schema and migration file
mix phx.gen.secret - Generates a secret
mix phx.gen.socket - Generates a Phoenix socket handler
mix phx.routes - Prints all routes
mix phx.server - Starts applications and their servers
mix compile.phoenix_live_view
mix phoenix_live_view.upgrade

5.0 KiB Raw Blame History