Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/auroratide/carica


https://github.com/auroratide/carica

Last synced: about 14 hours ago
JSON representation

Awesome Lists containing this project

README 

        
# Carica



**Carica** lets you embed characters into web pages! This library provides a number of semantic elements that help build interesting people from scratch. This can be useful for:



* Providing illustrations for colorfully teaching interesting topics

* Animating stories you have always wanted to tell

* Creating concept art for roleplaying games

* And many other things. Let your creativity run free!



## Disclaimer!



Carica is in its early phases (prior to version 1.0), and as such many things are subject to change. The goal is to define a set of standards that are flexible and intuitive as possible, granting the greatest sense of ease for both creating new Caricas and the models that compose them.



## A Quick Example



This image of Janet...



A girl with brown hair and blue eyes.



...was made using this HTML:



```html



  

    

    

    

    

    

  



```



## Installation



You can import Carica through CDN:



```html



```



Or, you may install Carica through NPM and include it as part of your build process:



```

npm i @auroratide/carica

```



```js

import '@auroratide/carica/lib/define.js`

```



## Using Carica



Carica is basically a collection of custom HTML elements.



Each element takes a **`src`** attribute indicating what actual model to draw to the screen.



```html



```



You can then customize the colors of that SVG's materials using **`color-*`** attributes. This is covered in greater detail below (see [Customizing Colors](#customizing-colors)), but for now since we know the hair SVG is composed of the "hair" material, we can change the color with `color-hair`:



```html



```



And finally, to make the shape accessible to everyone, the **`alt`** attribute is used to provide a textual representation.



```html



```



Building a Carica is as simple as assembling the different parts together and putting them under a single `carica-character` element!



```html



  



```



### Available Tags



**``** is the most basic tag available and represents any visible model. All other tags are based off `` but carry more semantic value:



* **``**: Represents a character such as a person; generally should contain all the parts belonging to a single character

* **``**: Represents the head of a character; generally should contain all the parts of a head, including hair and facial expressions

* **``**: Represents hair on a character, including the hair on top of the head or even facial hair

* **``**: Represents a character's mouth

* **`**: Represents the eyes of a character

* **``**: Represents the eyebrows above a character's eyes

* **``**: Represents eyelashes on a character's eyes, if any



Technically, all tags are _optional_ on a carica; for instance, a carica which does not have pronounced eyelashes does not need to specify a `` element.



Since all the above tags are entites, they all share the same attributes:



* **`src`**: The source SVG model to use; only `carica-head` has a default model

* **`alt`**: The textual replacement for a carica, mostly useful for assistive technologies

* **`color-*`**: A flexible set of attributes allowing you to define colors in-line; see [Customizing Colors](#customizing-colors)



### Customizing Colors



Each carica model is composed shapes, and each shape defines a **material** and a **shade**.



* The **material** of a shape is its primary composition, and can be thought of as the shape's main color.

* The **shade** is a variation of the material, such as "dark", or "light". A shape which does not specify a shade just uses the material's base color.



A single model can have shapes of different materials within it. For example, hair models usually just consist of shapes with the "hair" material, but it's possible for a hair model to have an in-built bow with material "hairbow" or "clothing".



Unfortunately, at the moment the only way to know what materials compose a model is to look at the model's source code.



The primary way to customize colors is through the inline `color-*` attributes. The asterisk is replaced with the material and shade you want to customize. Some examples:



* `color-hair="red"` makes all shapes with the `hair` material red.

* `color-skin="brown"` makes all shapes with the `skin` material brown.

* `color-hair-dark="darkred"` makes all shapes with the `hair` material and `dark` shade a dark red color.



It is also possible to use CSS to customize colors. Each material/shade combo is exposed as a CSS variable and as shadow parts. The following two CSS definitions will make dark hair into a dark red color.



```css

.janet carica-hair {

  --color-hair-dark: darkred;

}



.janet ::part(hair-material dark-shade) {

  fill: darkred;

}

```



### Carica Models



The `src` attribute lets you specify SVGs for the parts, but... what SVGs do you use?



At the moment there are very few models available, but the intent is to design the library in such a way that authoring new reusable models is easy.



For now, the only models that exist can be found here:



* [Auroratide Carica Models](https://github.com/Auroratide/carica-models)



## Authoring New Carica Models



It's honestly a bit early to author new models, as the details of how it should be done are still subject to change.



At the moment, [Auroratide Carica Models](https://github.com/Auroratide/carica-models) can be used as examples for how models may look. The important notes are:



* Each model should define the Carica namespace:

```xml



```

* Layers are defined with `carica:layer`.

* Material and shade are defined with `carica:material` and `carica:shade` respectively.