pikkujs/pikku-rtl
packages/cli/skills/pikku-rtl/SKILL.md
Make a Pikku frontend work in both English (LTR) and Arabic / right-to-left languages. Direction is derived from the active locale, applied once at the document root, and the layout mirrors itself — but only if styling is written flow-relative (margin-inline-start, text-align: start, Mantine ms/me) instead of left/right. TRIGGER when: adding Arabic (or Hebrew/Farsi/Urdu), asked to "support RTL / right-to-left / bidi / mirror the layout", or writing layout styles in an app that may run RTL. Builds on pikku-i18n (an RTL language is just another locale file). DO NOT TRIGGER for backend functions or for LTR-only copy changes.
$ install --global
skillsauthnpx skillsauth add pikkujs/pikku pikku-rtlInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jun 4, 2026, 6:07 AM120.7s1 file scanned
SKILL.md
- name:
- pikku-rtl
- description:
- Make a Pikku frontend work in both English (LTR) and Arabic / right-to-left languages. Direction is derived from the active locale, applied once at the document root, and the layout mirrors itself — but only if styling is written flow-relative (margin-inline-start, text-align: start, Mantine ms/me) instead of left/right. TRIGGER when: adding Arabic (or Hebrew/Farsi/Urdu), asked to "support RTL / right-to-left / bidi / mirror the layout", or writing layout styles in an app that may run RTL. Builds on pikku-i18n (an RTL language is just another locale file). DO NOT TRIGGER for backend functions or for LTR-only copy changes.
- installGroups:
- [core]
Pikku RTL (Arabic + English)
This skill sits on top of pikku-i18n. That skill maps a locale to t()
tokens; this one adds the second axis: a locale also has a direction.
Arabic is not special-cased — it is just another locale file (ar.json,
registered satisfies typeof en) plus the document being told it is rtl.
The one idea
Set dir once at the document root from the active locale, then let the
browser and Mantine mirror everything — provided every custom style is written
flow-relative (start/end), never physical (left/right). Get those two
things right and Arabic, Hebrew, Farsi and Urdu all work with zero per-component
RTL code.
Agent Operating Procedure
- Tokens first. Every visible string is already a
t()token viapikku-i18n. Arabic copy goes ini18n/ar.json, mirroringen.json's keys, registered withsatisfies typeof enso a missing key is a compile error. - Add the direction helper to the i18n config (one home for locale→dir):
(The bundled templates already ship this helper — use it, don't reinvent it.)const RTL_LOCALES = new Set(['ar', 'he', 'fa', 'ur']) export function localeDir(locale: string = defaultLocale): 'rtl' | 'ltr' { return RTL_LOCALES.has(locale.split('-')[0]) ? 'rtl' : 'ltr' } - Apply
dir+langat the root, once, from the active locale — pick the recipe for your framework below. - Write every layout style flow-relative. This is the part that actually makes mirroring work; see the rules. When editing existing UI to be RTL-ready, the job is mostly a search-and-replace of physical properties.
- Flip directional icons (chevrons, back/forward arrows) — the one thing logical properties can't do for you.
- Validate with the app's
tsc, then load?i18n-debug/ setdirand eyeball that the layout mirrors and nothing is stuck on the wrong edge.
Flow-relative, not physical — the rules that make it mirror
Use the inline-axis logical property; never the physical one:
| Don't (physical) | Do (flow-relative) |
| ---------------------------- | -------------------------------------------- |
| margin-left / marginLeft | margin-inline-start / marginInlineStart |
| margin-right | margin-inline-end / marginInlineEnd |
| padding-left/right | padding-inline-start/end |
| left: 0 / right: 0 | inset-inline-start: 0 / inset-inline-end |
| text-align: left/right | text-align: start / end |
| border-top-left-radius | border-start-start-radius |
| float: left/right | float: inline-start / inline-end |
In Mantine, use the logical style props — they emit the logical CSS above:
| Don't | Do |
| ----------- | ----------- |
| ml / mr | ms / me |
| pl / pr | ps / pe |
Mantine's own components already use logical properties internally, so once the direction is set they mirror automatically — you only have to be disciplined in your styles.
Leave flexbox and grid alone. display:flex already follows dir:
justify-content: flex-start resolves to the right edge under RTL on its own.
Never "fix" RTL by swapping to flex-direction: row-reverse or reordering DOM —
that double-flips and breaks the moment direction changes. The DOM order is
logical order; let dir handle the visual order.
Applying direction at the root
Mantine app (e.g. environment-template)
Mantine ships first-class RTL: wrap the tree in DirectionProvider and set the
matching dir on <html>.
import { DirectionProvider, MantineProvider } from '@mantine/core'
import i18n, { detectLocale, localeDir } from './i18n/config'
const locale =
typeof window !== 'undefined' ? detectLocale(window.location.pathname) : 'en'
const dir = localeDir(locale)
if (typeof document !== 'undefined') {
document.documentElement.lang = locale
document.documentElement.dir = dir // Mantine + browser read this
}
root.render(
<DirectionProvider initialDirection={dir}>
<MantineProvider theme={theme} defaultColorScheme="dark">
{/* …app… */}
</MantineProvider>
</DirectionProvider>
)
To flip direction live (a language switcher) call
document.documentElement.setAttribute('dir', localeDir(next)) and Mantine's
useDirection().setDirection(dir); both read the same value.
Plain Vite SPA (kanban, test-harness vite-spa)
No Mantine — just put dir/lang on <html> at bootstrap, after the locale is
detected (the same detectLocale the i18n config uses):
import { detectLocale, localeDir } from './i18n/config'
const locale = detectLocale(window.location.pathname)
document.documentElement.lang = locale
document.documentElement.dir = localeDir(locale)
Everything below inherits dir from <html>; logical CSS does the mirroring.
Vite SSR (test-harness vite-ssr)
The worker renders the full HTML, so set lang/dir on the server <html>
from the URL locale (the client inherits it on hydration — no flash):
import { detectLocale, localeDir } from './i18n/config'
const locale = detectLocale(new URL(request.url).pathname)
const dir = localeDir(locale)
const html = `<!doctype html>
<html lang="${locale}" dir="${dir}">
…
</html>`
i18next's active language must match: call i18n.changeLanguage(locale) before
renderToString so the SSR'd text and dir agree.
Next.js app-router (test-harness next-ssr / next-static)
Set it on the <html> in app/layout.tsx. With locale-prefixed routes the
segment gives the locale; for a single-locale build it's a constant:
import { localeDir, defaultLocale } from './i18n/config'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
const locale = defaultLocale // or the [lang] route segment / params
return (
<html lang={locale} dir={localeDir(locale)}>
<body>{children}</body>
</html>
)
}
For output: 'export' with /ar prefixes, derive locale from the route
segment so each statically-exported tree carries the right dir.
Directional icons — the manual bit
Logical properties mirror box layout, not glyphs. An icon that points
somewhere (chevron, back/next arrow, send, undo) must flip under RTL; a
non-directional icon (search, settings, avatar) must not. Flip with the
:dir() selector — no JS, no per-locale branching:
:dir(rtl) .icon-directional {
transform: scaleX(-1);
}
Or in CSS-in-JS / inline, gate on the resolved direction:
transform: localeDir(locale) === 'rtl' ? 'scaleX(-1)' : undefined.
Prefer logical icon components if your icon set ships them.
Arabic typography niceties
- Font: the default Latin stack renders Arabic with the system fallback,
which is inconsistent. Add an Arabic-capable family (e.g. Noto Sans Arabic,
IBM Plex Sans Arabic) to
font-familyso both scripts look intentional. - Numerals: don't hardcode digits. Format numbers/dates with
Intl.NumberFormat/Intl.DateTimeFormat(or i18next formatters) given the active locale, so Western vs Arabic-Indic digits follow the locale choice. - Line height: Arabic diacritics sit tall — a slightly larger
line-heighton Arabic body text avoids clipping. Keep it locale-scoped, not global.
Adding Arabic to an existing app — checklist
i18n/ar.jsonmirroringen.json; registerar: { translation: ar satisfies typeof en }and add'ar'tosupportedLocales. (Type-complete or it won't compile — the deploy blocks.)- Confirm the
localeDirhelper includesar(it does by default). - Confirm the root sets
dirfrom the locale (recipe above). - Sweep the app's styles: replace every
left/right,ml/mr,text-align: leftwith the flow-relative equivalent; revert any manualrow-reverse. - Flip directional icons.
tsc, then load the Arabic route and verify the whole layout mirrors — sidebar on the right, text right-aligned, arrows pointing the other way.
What NOT to do
- Don't use physical
left/right(orml/mr) in any new layout style — even in an English-only app. Writing logical from the start is the seam Arabic slots into, exactly like tokens are for copy. - Don't fake RTL with
flex-direction: row-reverse, reversed DOM order, or per-localeif (rtl)layout branches. Setdironce; let layout follow. - Don't set
diron individual components — it belongs on<html>so the whole document (and Mantine) agrees. - Don't translate Arabic copy outside the
t()token system; an RTL language is a normal locale, governed bypikku-i18n.
Related Skills
pikkujs/pikku-tag-middleware
documentation
VerifiedTrustedCommunity
Deprecated — use pikku-middleware instead. Tag middleware (addTagMiddleware) is now documented as a section within the pikku-middleware skill, alongside global HTTP middleware, execution order, and the service-to-service bearer auth pattern.
56SKILL.mdUpdated Jun 10, 2026
pikkujs/pikku-permissions
testing
VerifiedTrustedCommunity
Use when adding authorization checks to Pikku functions or routes — pikkuPermission, pikkuAuth, per-function permissions, pattern-based permissions, or understanding OR/AND permission logic. TRIGGER when: user wants to restrict who can call a function, check resource ownership, add role-based access, or understand where permission checks belong. DO NOT TRIGGER when: user asks about middleware or request interception (use pikku-middleware), authentication strategies (use pikku-security), or session management.
56SKILL.mdUpdated Jun 10, 2026
pikkujs/pikku-middleware
testing
VerifiedTrustedCommunity
Use when adding any middleware to a Pikku app — global HTTP middleware, tag-scoped middleware (including service-to-service bearer auth), per-route middleware, session-setting middleware, or understanding middleware execution order and priority. TRIGGER when: user wants middleware on some or all routes, machine-to-machine auth, tag-scoped cross-cutting concerns, global interceptors, or middleware priority/order questions. DO NOT TRIGGER when: user asks about permissions/authorization checks (use pikku-permissions), auth strategies like authBearer/authCookie (use pikku-security), or deployment.
56SKILL.mdUpdated Jun 10, 2026
pikkujs/pikku-template-clone
documentation
VerifiedTrustedCommunity
Standard cleanup to run right after a Pikku template is cloned or scaffolded into a new project. TRIGGER when: a Pikku template was just cloned/scaffolded (via `pikku create`, `git clone <template>`, or the user says "I cloned the kanban template / starter / template"), or the working tree still looks like an untouched template (template README, placeholder `@project/*` name in package.json). DO NOT TRIGGER when: working in an established project mid-feature, or editing the template repo itself.
56SKILL.mdUpdated Jun 4, 2026