# Edit theme

The theme uses a modern development stack to compile and optimize styles and scripts.

For advanced customization, it is recommended that you are familiar with using the command line and code editors such as [Visual Studio Code](https://code.visualstudio.com/) or [Sublime Text](https://www.sublimetext.com/). A compatible version of [Node.js](https://nodejs.org/) is also required to manage project dependencies.

### Stack Overview

The theme is built using the following tools:

* [**Gulp**](https://gulpjs.com/) - Task runner for automating build processes *(used in Ghost’s official themes)*
* [**Tailwind CSS**](https://tailwindcss.com/) - Utility-first CSS framework used for styling.
* [**BrowserSync**](https://browsersync.io/) - Enables live reload and multi-device testing.
* [**gscan**](https://github.com/TryGhost/gscan) - Ghost’s theme validator.

You can use either **npm** or **yarn** to install and manage dependencies.

### Available Commands

{% tabs %}
{% tab title="npm" %}

```bash
npm install    # Install theme dependencies
npm run dev    # Starts development mode with live reload
npm run test   # Runs gscan to check for compatibility issues
npm run zip    # Builds a .zip file of the theme
```

{% endtab %}
{% endtabs %}

### Development Mode

When running in development mode, two URLs will be generated:

* `http://localhost:3000` – Local preview.
* `http://<your-ip>:3000` – For multi-device testing on the same network.

These preview URLs **proxy your local Ghost site**, which must be running in the background.

Use your Ghost site URL (e.g., `http://localhost:2368/ghost`) to access the admin panel.

### Custom Theming

The theme uses a variable-based theming system defined in the `assets/css/pina.css` file. This approach allows it to manage fonts, color palettes, and dark mode behavior using CSS custom properties.

By centralizing these values, it becomes easier to:

* Create and adjust **color schemes.**
* Maintain consistent styling across light and dark modes.
* Extend the theme with new design options.

This system improves flexibility while keeping the codebase clean and easy to maintain.

### Custom Components

The theme includes a set of **custom Tailwind-based utilities** defined in the `assets/css/utilities.css` file.

These utilities are used throughout the theme to ensure **consistency** and to simplify the development of more **advanced and flexible features**.

They include:

* **Containers** - for layout structure.
* **Layout helpers** - such as wrappers, spacers, and grid utilities.
* **Headings** - with preset spacing and font styles.
* **Buttons** - with consistent appearance across the site.

This setup allows for faster iteration and easier maintenance when building new functionality into the theme.

### Custom Cards

**Sand**  uses **custom Tailwind styles** and **local JavaScript** to improve the appearance and performance of Ghost cards.

This ensures visual consistency across all devices and removes the need for external scripts.

### Custom CSS

The following steps are for adding custom CSS only. If you need to change existing styles or modify layout components, edit the corresponding `.hbs` templates directly  this is the standard approach when using Tailwind CSS.

Follow the steps below to add your own custom styles:

{% stepper %}
{% step %}
**Create the Custom File**

* Create a new file in `assets/css/` example: `custom.css`
  {% endstep %}

{% step %}
**Add Your CSS**

* Write your styles inside the `custom.css` file that was created.

```css
/* Example */
.custom-button {
    background-color: #000;
    color: #fff;
    padding-block: 0.5rem;
    padding-inline: 1rem;
    border-radius: 0.5rem;
}
```

{% endstep %}

{% step %}
**Import the File**

* At the end of  `assets/css/tailwind.css` import your custom file.
  {% endstep %}
  {% endstepper %}

This ensures your styles are included in the final build and take advantage of Tailwind’s optimization.

### Simple Edits (No Build Required)

For small changes such as:

* [Translate](https://pinathemes.gitbook.io/docs/sand/advanced/translate)
* [Posts per page](https://pinathemes.gitbook.io/docs/sand/advanced/posts-per-page)

You don’t need to install dependencies or run Ghost locally. These can be done by directly editing the theme files.
