Preline MCP

Intent

Use this skill to integrate Preline UI components and blocks into HTML files via the Preline MCP server. The server exposes 6 tools that return integration-ready HTML, CSS, and JS.

Activate when:

User says "preline", "add preline", "/preline", "use preline"
User asks for a Tailwind CSS component from the Preline library
User asks for a block (ready-made page section) or a starter page

Defaults

Never guess slugs. All section, component, and category identifiers are exact kebab-case strings. Always discover them via
```
components_list
```
or
```
blocks_categories
```
first.
One at a time. Retrieve one component or block, integrate it fully, then move to the next.
Always read the target file before inserting anything.
Call
```
components_list({ section: "<inferred-slug>" })
```
when the component type is known - this keeps the response small. Omit section only when unsure.

Decision: Component vs Block

User says	Use
"component" / "components"	Component workflow
"block" / "blocks" (or "example" / "examples")	Block workflow
Ambiguous	Use judgment; blocks give more complete results

Clarifying Vague Requests

Ask the user to pick instead of guessing in either of these cases:

Abstract request. Too abstract to confidently map onto one category/section, let alone one block/component - e.g. "give me something for a pricing page", "I need a nice form", "show me a dashboard example". Start at step 1 below.
Tied candidates. The request is concrete enough to reach a single category/section, but
```
blocks_in_category
```
/
```
components_list({ section })
```
still leaves 2+ candidates whose titles + descriptions satisfy every criterion the request named about equally well (same layout/feature/style class), with nothing in the request to break the tie. Skip straight to step 3 below with just the tied candidates.

If exactly one candidate matches everything the request names ("a basic accordion", "the SaaS hero with tabs"), skip straight to the normal workflow - don't interrogate the user for things you can already resolve, and don't ask just to be safe when one option is clearly the best fit.

All clarifying questions and lists are in English by default - switch to the user's language only once they write to you in it.

Blocks:

Ask which category fits. Call
```
blocks_categories()
```
and present the relevant
```
mainSection / subSection / category
```
paths with their titles and descriptions - the catalog carries a one-line description for every category, so present it directly rather than inventing your own summary.
Try to resolve in one round. If the user's reply both names a category and describes the item distinctively enough to identify a single match (a specific layout, feature, or style), call
```
blocks_in_category
```
to confirm the exact ID and go straight to
```
single_block
```
- skip step 3 entirely.
Otherwise, ask which block fits best. Call
```
blocks_in_category({ mainSection, subSection, category })
```
, list the block titles + descriptions - or just the tied candidates, for the case above - and ask the user to pick the one closest to their needs.
Fetch and integrate the chosen block with
```
single_block
```
.

Components - same shape, sections instead of categories:

Ask which section fits (
```
components_list()
```
for the full list, or
```
components_list({ section })
```
once you can infer one).
If the reply names a section and describes the component distinctively enough → resolve directly via
```
single_component
```
(lean on
```
relative
```
metadata - see Smart Component Selection - to land on the right default/variant).
Otherwise list the components in that section (titles + descriptions, with
```
relative.category
```
groupings where present - or just the tied candidates, for the case above) and ask which fits best.
Fetch and integrate with
```
single_component
```
.

Keep each round to one focused question with a short, scannable list - that beats an open "what do you want?" and beats guessing a slug just to avoid asking.

Composite & Layout Requests

When a request describes more than a single component - several pieces, a region, a full page, or an app shell - don't fetch ad-hoc. Plan the whole result first, then fetch and integrate one node at a time. The same steps apply to any shape: a dashboard, a settings page, a product page, a multi-step form, "a card/section/layout with X, Y and Z", etc.

Lock cross-cutting constraints first. Anything that applies to the whole result - class system (theme tokens vs utilities →
```
isUtilityBased
```
/
```
theme
```
), shared surfaces/colors, spacing/density, repeated element states - decide once, up front. Keep it identical across every later fetch and edit.
Decompose into a tree: containers → regions → leaf components. Write it down; each leaf is one fetch.
Discover every node - route, then confirm. Use references/catalog-map.md to route: an abstract intent (a whole page/region/shell) → the right
```
blocks_categories
```
branch (reuse a ready-made block as the skeleton when one fits); each named element → the right
```
components_list({ section })
```
. The map only tells you where to look - always confirm the exact slug against the tool output before inserting.
Assemble outermost-first, one at a time. The skeleton/outer container sets the shared surfaces and the script/init anchors; then fill inward region by region, integrating each fully (Integration Rules) before the next. Keep the returned classes, change text only - except the specific surfaces/colors/states the user asked to change. Apply every structural adaptation to the markup before writing it (see Adapt before you write in Integration Rules).
Verify the finished result against the request, element by element.

See references/composite-layouts.md for the expanded method and worked illustrations.

Workflow: Components

1. components_list({ section: "<slug>" })   → get valid component IDs
2. single_component({ section, component }) → get HTML/CSS/JS
3. Read target file
4. Integrate HTML, CSS, scripts, init (see Integration Rules)
5. Repeat from step 1 only after integration is complete

Workflow: Blocks

1. blocks_categories()                                    → get hierarchy
2. blocks_in_category({ mainSection, subSection, category }) → get block IDs
3. single_block({ mainSection, subSection, category, block }) → get HTML/CSS/JS
4. Read target file
5. Integrate HTML, CSS, scripts, init (see Integration Rules)
6. Repeat from step 1 only after integration is complete

Integration Rules

HTML - insert where the user needs it.

CSS (

<!-- CSS -->

section):

MUST go inside
```
<head>
```
, immediately before
```
</head>
```
NEVER place in
```
<body>
```
or near
```
</body>
```

External scripts (

<!-- Scripts -->

section):

The
```

```
label is a response section marker - NOT a location in the target file
Placement algorithm: open target file, scan upward from
```
</body>
```
, skipping blank lines, comments, and non-structural tags (
```
</script>
```
,
```
</style>
```
, etc.)
The first structural closing tag you reach (
```
</main>
```
,
```
</section>
```
,
```
</div>
```
,
```
</footer>
```
,
```
</article>
```
) is the anchor
Insert
```
<script src>
```
tags after that anchor, ordered around the existing Preline core script - the loaded
```
<script src>
```
whose
```
src
```
contains
```
preline
```
(e.g.
```
…/preline/dist/index.js
```
; exact path varies by install):
- scripts whose
```
src
```
  does not contain
```
preline
```
  (third-party libs: lodash, apexcharts, …) → before the Preline core script
- scripts whose
```
src
```
  does contain
```
preline
```
  (Preline helpers, e.g.
```
hs-*-helpers.js
```
  ) → after the Preline core script
- if no Preline core script exists yet, keep order: scripts without
```
preline
```
  , then scripts with
```
preline
```
- inline init
```
<script>
```
  always comes last, immediately before
```
</body>
```

Init (

<!-- Init -->

section):

Place immediately before
```
</body>
```

Wrap in

window.addEventListener('load', () => { ... })

unless the block already contains

<script>

Smart Component Selection

components_list

may return a

relative

object per component:

```
isSectionDefault: true
```
- recommended default for the section; prefer when the request is vague
- Exception: if the description says "multiple variants" and the user wants one, pick a single-variant component instead
```
category
```
- logical group (e.g.
```
"color-variants"
```
,
```
"states"
```
)
```
isCategoryDefault: true
```
- recommended default for its category; prefer when the request implies a style group

Available Themes

default

(blue) ·

harvest

(amber) ·

retro

(fuchsia) ·

moon

(grayscale) ·

ocean

(cyan) ·

bubblegum

(pink) ·

cashmere

(mauve) ·

autumn

(orange) ·

olive

(green)

Pass via

isUtilityBased: true, theme: "<name>"

single_component

single_block

Key References

references/catalog-map.md - routing map: block intent ontology (whole pages/shells) + all component sections grouped by purpose, JS-plugin marked. Open this to pick the right
```
section
```
/ blocks branch before any discovery call.
references/composite-layouts.md - full method for multi-component / page / shell requests, with worked illustrations
references/mcp-tools-reference.md - full parameter specs, placement algorithm detail, all 6 tools

preline-mcp

NPX Install

Tags

SKILL.md Content

Preline MCP

Intent

Defaults

Decision: Component vs Block

Clarifying Vague Requests

Composite & Layout Requests

Workflow: Components

Workflow: Blocks

Integration Rules

Smart Component Selection

Available Themes

Key References