# animal-island-ui: React components with one style import you cannot forget > animal-island-ui is a React and TypeScript component library with an original cozy island design language, published to npm with ESM, CommonJS and type entry points side by side. The single detail that decides whether your first render works is one import line, and the package exports it as a subpath: `animal-island-ui/style`. **guokaigdg/animal-island-ui** — A Kawaii React UI component library 一个可爱的 React UI 组件库 - Repository: https://github.com/guokaigdg/animal-island-ui - Website: https://guokaigdg.github.io/animal-island-ui/ - Stars: 4,738 · Forks: 18 - Language: TypeScript - License: MIT - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/guokaigdg-animal-island-ui ## Without the style import the components render bare The README puts a warning above the first example, and it is the most useful line in the document: ```tsx import { Button, Card } from 'animal-island-ui'; import 'animal-island-ui/style'; function App() { return (
Welcome to the island!
); } ``` The warning says to make sure you import the styles with `import 'animal-island-ui/style'`, otherwise the components will have no styles or fonts. Fonts are part of that sentence, which is the tell: this library ships its own typeface alongside the CSS, so a missing import is not a cosmetic problem but an unstyled page with fallback fonts. The manifest resolves that subpath to `./dist/index.css`, so the import is a real package entry rather than a deep path into the build. ## Three module formats and two subpath escapes The exports map is conventional and worth reading once. `main` points at `dist/cjs/index.cjs`, `module` at `dist/es/index.js` and `types` at `dist/types/index.d.ts`, and the `.` export repeats those three under `types`, `import` and `require` keys. Two subpaths sit beside it: `./style` for the stylesheet, and `./dist/index.css` for the same file by path. Then there are two wildcard entries, `./es/*` and `./items/*`, which exist so a consumer can reach the ES module build and the item definitions directly. `sideEffects` is set to false, so a bundler can drop unused components, and the published `files` list is only `dist`, `items.d.ts` and `README.md`. The manifest describes the library as a nature-inspired React component library and is marked as an ES module package. ## Building the library, the demo and the GitHub Pages site are three scripts The scripts separate the artifact you publish from the artifact you preview. `dev` is `vite` for the demo development server, `build` is `vite build && tsc --project tsconfig.build.json --emitDeclarationOnly`, so the bundle is produced by Vite while the declaration files are emitted by a second TypeScript invocation, and `build:demo` is `vite build --config vite.config.demo.ts` against a different configuration file. Publishing is guarded by `prepublishOnly` running the build first, so a release cannot ship a stale bundle. Deployment is `npm run build:demo && gh-pages -d demo-dist`, which is how the online preview at the project's GitHub Pages URL stays in step with the library. ## Two vitest configs means accessibility is its own run Testing is split rather than merged. `test` is `vitest` in watch mode, `test:run` is `vitest run && vitest run --config vitest.a11y.config.ts`, and there is a dedicated `test:a11y` script for the accessibility configuration alone. Coverage writes machine readable output with `--reporter=json --outputFile=coverage/vitest-results.json`, and a separate script, `badges`, runs `node scripts/generate-coverage-badges.mjs` to turn that file into the badge the README shows. There is also `check:docs` running `node scripts/check-docs-sync.mjs`, which is a check that the documentation and the components have not drifted apart. Linting is `eslint .` with a flat config, and type checking has its own script with three tsconfig files: the base one, `tsconfig.build.json` for declarations and `tsconfig.test.json` for the suite. ## The design system directory is the single source of truth The documentation is routed by audience, and the routing tells you where to look. `docs/design-system/` is the canonical definition: tokens, design rules, pixel-exact per component specifications and a CSS variable template. Everything else points back at it. `docs/design-prompts.md` holds prompts for design and image tools, naming v0, Figma AI, Midjourney and DALL-E, and links to the canonical spec files rather than restating them. `docs/adr/` holds architecture decision records, `docs/development/` the repository's own development guide, and `AGENTS.md` is the entry point for coding agents working here, joined by `CLAUDE.md` and a `.trae/` directory at the root. The claim that every visual element, layout, icon and animation is crafted from scratch is what the pixel-exact specs exist to keep honest. ## Two ways in for AI tools, and one of them needs no npm The project treats AI tooling as a first class install target. The first option is an installable skill, recommended for AI coding agents, added with `skills add guokaigdg/animal-island-ui`, and its reference set lives in `skills/animal-island-ui-style/` with per component props. The second option is for people who do not want to write code at all: a one-click prompt in `docs/one-click-prompt.md`, in four steps. Copy the prompt block, paste it into any AI tool that can fetch URLs, among them Cursor, Claude, ChatGPT, Gemini, v0 and Bolt, answer when the tool asks what page you want in one phrase such as personal blog, product list or FAQ, then save the `index.html` it returns and double-click to preview. No npm and no build step on that path. ## The icon set and the Vue version live in sibling repositories Two related projects are named in the README, both by the same author. The icons come from `naive-icons`, and the Vue version of the whole component set is `animal-island-vue`, which is the clearest signal about the scope of this library: it is the React implementation of a design language that exists in both frameworks. The demo application in this repository is where you can see the components composed: `demo/App.tsx`, `demo/ComponentPage.tsx` and `demo/HomePage.tsx` sit beside `demo/gradients.ts`, `demo/pageInfo.ts`, `demo/fonts.css`, `demo/components/`, `demo/tools/` and `demo/assets/`, with `index.html` at the repository root as the Vite entry. Two Vite configs and two Vitest configs cover library and demo work separately. Around them sit the ordinary files of a maintained package: a `CHANGELOG.md`, `.editorconfig`, `.prettierrc` with a matching `.prettierignore`, a `.githooks/` directory, `eslint.config.js` and a lockfile. Version numbers are the one loose end: the manifest reads 2.1.0 while the newest release tag is v2.0.0 from 2026-09-24, after v1.13.0 and v1.12.0 in the weeks before it, so the tree is ahead of the last tag. The last recorded push is dated 2026-10-03. ## Conclusion Adopt animal-island-ui if you want a component library with a coherent design language and generated specs rather than an assembled set of borrowed pieces, and if your build can carry one extra CSS import. Do not adopt it if you need a component that the library does not ship, since the design system is defined per component and adding one is project work. Verify first that `import 'animal-island-ui/style'` is in your entry file, read the design system document before you start overriding anything, and pin a version, since the manifest reads 2.1.0 while the newest release tag is v2.0.0. ## FAQ ### What is Animal-Island-UI? A lightweight React and TypeScript component library with an original, cozy island-style design language, where every visual element, layout, icon and animation is crafted from scratch. It is published to npm as animal-island-ui under the MIT license. ### How do I install and start using Animal-Island-UI? Run npm install animal-island-ui, import the components you need, and import the styles separately with import 'animal-island-ui/style'. The README warns that without that import the components will have no styles or fonts, which is the most common first-run failure. ### Does Animal-Island-UI ship a skill for AI coding agents? Yes. The repository ships an installable agent skill added with skills add guokaigdg/animal-island-ui, and a one-click prompt in docs/one-click-prompt.md where you paste a bootstrap block into an AI tool that can fetch URLs and save the index.html it returns. ### How do I run the Animal-Island-UI demo locally? Clone the repository, run npm install, then npm run dev for the Vite development server. The library itself is built with npm run build, the demo site with npm run build:demo against vite.config.demo.ts, and npm run deploy publishes demo-dist with gh-pages. ### Can I use Animal-Island-UI in a commercial product? The licence section says it is distributed under the MIT License, which permits using, copying, modifying, merging, publishing, distributing, sublicensing and selling copies, including in commercial products, as long as the copyright and permission notice travel with copies. It is provided as is, without warranty of any kind. ## Sources - [guokaigdg/animal-island-ui on GitHub](https://github.com/guokaigdg/animal-island-ui) - [Issues](https://github.com/guokaigdg/animal-island-ui/issues) - [Project website](https://guokaigdg.github.io/animal-island-ui/) - [README](https://github.com/guokaigdg/animal-island-ui/blob/main/README.md) - [Releases](https://github.com/guokaigdg/animal-island-ui/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/guokaigdg-animal-island-ui